GLib.OptionContext¶

Fields¶

None

Methods¶

	`add_group` (group)
	`add_main_entries` (entries, translation_domain)
	`free` ()
	`get_description` ()
	`get_help` (main_help, group)
	`get_help_enabled` ()
	`get_ignore_unknown_options` ()
	`get_main_group` ()
	`get_strict_posix` ()
	`get_summary` ()
	`parse` (argv)
	`parse_strv` (arguments)
	`set_description` (description)
	`set_help_enabled` (help_enabled)
	`set_ignore_unknown_options` (ignore_unknown)
	`set_main_group` (group)
	`set_strict_posix` (strict_posix)
	`set_summary` (summary)
	`set_translate_func` (func, *data)
	`set_translation_domain` (domain)

Details¶

class GLib.OptionContext¶

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:

testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2

The example demonstrates a number of features of the GOption commandline parser:

Options can be single letters, prefixed by a single dash.
Multiple short options can be grouped behind a single dash.
Long options are prefixed by two consecutive dashes.
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, which is useful if the extra argument starts with a dash, which would otherwise cause it to be interpreted as another option.
Non-option arguments are returned to the application as rest arguments.
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.

Another important feature of GOption is that it can automatically generate nicely formatted help output. Unless it is explicitly turned off with GLib.OptionContext.set_help_enabled(), GOption will recognize the --help, -?, --help-all and --help-groupname options (where groupname is the name of a GLib.OptionGroup) and write a text similar to the one shown in the following example to stdout.

Usage:
  testtreemodel [OPTION...] - test tree model performance

Help Options:
  -h, --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

GOption groups options in GLib.OptionGroups, 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 GLib.OptionContext, and parse all options by a single call to GLib.OptionContext.parse(). See gtk_get_option_group() for an example.

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 GLib.OptionContext.parse().

Here is a complete example of setting up GOption to parse the example commandline above and produce the example help output.

static gint repeats = 2;
static gint max_size = 8;
static gboolean verbose = FALSE;
static gboolean beep = FALSE;
static gboolean randomize = FALSE;

static GOptionEntry entries[] =
{
  { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
  { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
  { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
  { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
  { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
  G_OPTION_ENTRY_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, &argc, &argv, &error))
    {
      g_print ("option parsing failed: %s\n", error->message);
      exit (1);
    }

  ...

}

On UNIX systems, the argv that is passed to main() has no particular encoding, even to the extent that different parts of it may have different encodings. In general, normal arguments and flags will be in the current locale and filenames should be considered to be opaque byte strings. Proper use of GLib.OptionArg.FILENAME vs GLib.OptionArg.STRING is therefore important.

Note that on Windows, filenames do have an encoding, but using GLib.OptionContext with the argv as passed to main() will result in a program that can only accept commandline arguments with characters from the system codepage. This can cause problems when attempting to deal with filenames containing Unicode characters that fall outside of the codepage.

A solution to this is to use g_win32_get_command_line() and GLib.OptionContext.parse_strv() which will properly handle full Unicode filenames. If you are using #GApplication, this is done automatically for you.

The following example shows how you can use GLib.OptionContext directly in order to correctly deal with Unicode filenames on Windows:

int
main (int argc, char **argv)
{
  GError *error = NULL;
  GOptionContext *context;
  gchar **args;

#ifdef G_OS_WIN32
  args = g_win32_get_command_line ();
#else
  args = g_strdupv (argv);
#endif

  // set up context

  if (!g_option_context_parse_strv (context, &args, &error))
    {
      // error happened
    }

  ...

  g_strfreev (args);

  ...
}

add_group(group)[source]¶

Parameters:: group (GLib.OptionGroup) – the group to add

Adds a GLib.OptionGroup to the self, so that parsing with self will recognize the options in the group. Note that this will take ownership of the group and thus the group should not be freed.

New in version 2.6.

add_main_entries(entries, translation_domain)[source]¶

Parameters:

entries ([GLib.OptionEntry]) – a None-terminated array of GLib.OptionEntrys
translation_domain (str or None) – a translation domain to use for translating the --help output for the options in entries with gettext(), or None

A convenience function which creates a main group if it doesn’t exist, adds the entries to it and sets the translation domain.

New in version 2.6.

free()[source]¶

Frees context and all the groups which have been added to it.

Please note that parsed arguments need to be freed separately (see GLib.OptionEntry).

New in version 2.6.

get_description()[source]¶

Returns:: the description
Return type:: str

Returns the description. See GLib.OptionContext.set_description().

New in version 2.12.

get_help(main_help, group)[source]¶

Parameters:

main_help (bool) – if True, only include the main group
group (GLib.OptionGroup or None) – the GLib.OptionGroup to create help for, or None

Returns:

A newly allocated string containing the help text

Return type:

str

Returns a formatted, translated help text for the given context. To obtain the text produced by --help, call g_option_context_get_help (context, TRUE, NULL). To obtain the text produced by --help-all, call g_option_context_get_help (context, FALSE, NULL). To obtain the help text for an option group, call g_option_context_get_help (context, FALSE, group).

New in version 2.14.

get_help_enabled()[source]¶

Returns:: True if automatic help generation is turned on.
Return type:: bool

Returns whether automatic --help generation is turned on for self. See GLib.OptionContext.set_help_enabled().

New in version 2.6.

get_ignore_unknown_options()[source]¶

Returns:: True if unknown options are ignored.
Return type:: bool

Returns whether unknown options are ignored or not. See GLib.OptionContext.set_ignore_unknown_options().

New in version 2.6.

get_main_group()[source]¶

Returns:: the main group of self, or None if self doesn’t have a main group. Note that group belongs to self and should not be modified or freed.
Return type:: GLib.OptionGroup

Returns a pointer to the main group of self.

New in version 2.6.

get_strict_posix()[source]¶

Returns:: True if strict POSIX is enabled, False otherwise.
Return type:: bool

Returns whether strict POSIX code is enabled.

See GLib.OptionContext.set_strict_posix() for more information.

New in version 2.44.

get_summary()[source]¶

Returns:: the summary
Return type:: str

Returns the summary. See GLib.OptionContext.set_summary().

New in version 2.12.

parse(argv)[source]¶

Parameters:

argv ([str]) – a pointer to the array of command line arguments

Raises:

GLib.Error

Returns:

True if the parsing was successful, False if an error occurred

argv:: a pointer to the array of command line arguments

Return type:

(bool, argv: [str])

Parses the command line arguments, recognizing options which have been added to self. A side-effect of calling this function is that GLib.set_prgname() will be called.

If the parsing is successful, any parsed arguments are removed from the array and argc and argv are updated accordingly. A ‘–’ option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with ‘-’. In case of an error, argc and argv are left unmodified.

If automatic --help support is enabled (see GLib.OptionContext.set_help_enabled()), and the argv array contains one of the recognized help options, this function will produce help output to stdout and call exit (0).

Note that function depends on the current locale for automatic character set conversion of string and filename arguments.

New in version 2.6.

parse_strv(arguments)[source]¶

Parameters:

arguments ([str]) – a pointer to the command line arguments (which must be in UTF-8 on Windows). Starting with GLib 2.62, arguments can be None, which matches GLib.OptionContext.parse().

Raises:

GLib.Error

Returns:

True if the parsing was successful, False if an error occurred

arguments:: a pointer to the command line arguments (which must be in UTF-8 on Windows). Starting with GLib 2.62, arguments can be None, which matches GLib.OptionContext.parse().

Return type:

(bool, arguments: [str])

Parses the command line arguments.

This function is similar to GLib.OptionContext.parse() except that it respects the normal memory rules when dealing with a strv instead of assuming that the passed-in array is the argv of the main function.

In particular, strings that are removed from the arguments list will be freed using GLib.free().

On Windows, the strings are expected to be in UTF-8. This is in contrast to GLib.OptionContext.parse() which expects them to be in the system codepage, which is how they are passed as argv to main(). See g_win32_get_command_line() for a solution.

This function is useful if you are trying to use GLib.OptionContext with #GApplication.

New in version 2.40.

set_description(description)[source]¶

Parameters:: description (str or None) – a string to be shown in --help output after the list of options, or None

Adds a string to be displayed in --help output after the list of options. This text often includes a bug reporting address.

Note that the summary is translated (see GLib.OptionContext.set_translate_func()).

New in version 2.12.

set_help_enabled(help_enabled)[source]¶

Parameters:: help_enabled (bool) – True to enable --help, False to disable it

Enables or disables automatic generation of --help output. By default, GLib.OptionContext.parse() recognizes --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.

New in version 2.6.

set_ignore_unknown_options(ignore_unknown)[source]¶

Parameters:: ignore_unknown (bool) – True to ignore unknown options, False to produce an error when unknown options are met

Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the argv array after parsing. By default, GLib.OptionContext.parse() treats unknown options as error.

This setting does not affect non-option arguments (i.e. arguments which don’t start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.

New in version 2.6.

set_main_group(group)[source]¶

Parameters:: group (GLib.OptionGroup) – the group to set as main group

Sets a GLib.OptionGroup as main group of the self. This has the same effect as calling GLib.OptionContext.add_group(), the only difference is that the options in the main group are treated differently when generating --help output.

New in version 2.6.

set_strict_posix(strict_posix)[source]¶

Parameters:: strict_posix (bool) – the new value

Sets strict POSIX mode.

By default, this mode is disabled.

In strict POSIX mode, the first non-argument parameter encountered (eg: filename) terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed.

If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options.

As an example, consider “ls foo -l”. With GNU style parsing, this will list “foo” in long mode. In strict POSIX style, this will list the files named “foo” and “-l”.

It may be useful to force strict POSIX mode when creating “verb style” command line tools. For example, the “gsettings” command line tool supports the global option “–schemadir” as well as many subcommands (“get”, “set”, etc.) which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing).

New in version 2.44.

set_summary(summary)[source]¶

Parameters:: summary (str or None) – a string to be shown in --help output before the list of options, or None

Adds a string to be displayed in --help output before the list of options. This is typically a summary of the program functionality.

Note that the summary is translated (see GLib.OptionContext.set_translate_func() and GLib.OptionContext.set_translation_domain()).

New in version 2.12.

set_translate_func(func, *data)[source]¶

Parameters:

func (GLib.TranslateFunc or None) – the GLib.TranslateFunc, or None
data (object or None) – user data to pass to func, or None

Sets the function which is used to translate the contexts user-visible strings, for --help output. If func is None, strings are not translated.

Note that option groups have their own translation functions, this function only affects the parameter_string (see g_option_context_new()), the summary (see GLib.OptionContext.set_summary()) and the description (see GLib.OptionContext.set_description()).

If you are using gettext(), you only need to set the translation domain, see GLib.OptionContext.set_translation_domain().

New in version 2.12.

set_translation_domain(domain)[source]¶

Parameters:: domain (str) – the domain to use

A convenience function to use gettext() for translating user-visible strings.

New in version 2.12.