Commandline option parser

Commandline option parser — parses commandline options

Functions

Types and Values

Includes

#include <glib.h>

Description

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 g_option_context_set_help_enabled(), GOption will recognize the --help, -?, --help-all and --help-groupname options (where groupname is the name of a GOptionGroup) and write a text similar to the one shown in the following example to stdout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 GOptionGroups, 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.

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().

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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 G_OPTION_ARG_FILENAME vs G_OPTION_ARG_STRING is therefore important.

Note that on Windows, filenames do have an encoding, but using GOptionContext 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 g_option_context_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 GOptionContext directly in order to correctly deal with Unicode filenames on Windows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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);

  ...
}

Functions

GOptionArgFunc ()

gboolean
(*GOptionArgFunc) (const gchar *option_name,
                   const gchar *value,
                   gpointer user_data,
                   GError **error);

The type of function to be passed as callback for G_OPTION_ARG_CALLBACK options.

Parameters

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.

 

user_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()


g_option_context_new ()

GOptionContext *
g_option_context_new (const gchar *parameter_string);

Creates a new option context.

The parameter_string can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the GOptionContext, typically something like "FILES" or "FILE1 FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the arg_description of the corresponding GOptionEntry in the usage summary.

Another usage is to give a short summary of the program functionality, like " - frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use g_option_context_set_summary().

Note that the parameter_string is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated.

Parameters

parameter_string

a string which is displayed in the first line of --help output, after the usage summary programname [OPTION...].

[nullable]

Returns

a newly created GOptionContext, which must be freed with g_option_context_free() after use.

Since: 2.6


g_option_context_set_summary ()

void
g_option_context_set_summary (GOptionContext *context,
                              const gchar *summary);

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 g_option_context_set_translate_func() and g_option_context_set_translation_domain()).

Parameters

context

a GOptionContext

 

summary

a string to be shown in --help output before the list of options, or NULL.

[nullable]

Since: 2.12


g_option_context_get_summary ()

const gchar *
g_option_context_get_summary (GOptionContext *context);

Returns the summary. See g_option_context_set_summary().

Parameters

context

a GOptionContext

 

Returns

the summary

Since: 2.12


g_option_context_set_description ()

void
g_option_context_set_description (GOptionContext *context,
                                  const gchar *description);

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 g_option_context_set_translate_func()).

Parameters

context

a GOptionContext

 

description

a string to be shown in --help output after the list of options, or NULL.

[nullable]

Since: 2.12


g_option_context_get_description ()

const gchar *
g_option_context_get_description (GOptionContext *context);

Returns the description. See g_option_context_set_description().

Parameters

context

a GOptionContext

 

Returns

the description

Since: 2.12


GTranslateFunc ()

const gchar *
(*GTranslateFunc) (const gchar *str,
                   gpointer user_data);

The type of functions which are used to translate user-visible strings, for <option>--help</option> output.

Parameters

str

the untranslated string

 

user_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.


g_option_context_set_translate_func ()

void
g_option_context_set_translate_func (GOptionContext *context,
                                     GTranslateFunc func,
                                     gpointer data,
                                     GDestroyNotify destroy_notify);

Sets the function which is used to translate the contexts user-visible strings, for --help output. If func is NULL, 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 g_option_context_set_summary()) and the description (see g_option_context_set_description()).

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

Parameters

context

a GOptionContext

 

func

the GTranslateFunc, or NULL.

[nullable]

data

user data to pass to func , or NULL.

[nullable]

destroy_notify

a function which gets called to free data , or NULL.

[nullable]

Since: 2.12


g_option_context_set_translation_domain ()

void
g_option_context_set_translation_domain
                               (GOptionContext *context,
                                const gchar *domain);

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

Parameters

context

a GOptionContext

 

domain

the domain to use

 

Since: 2.12


g_option_context_free ()

void
g_option_context_free (GOptionContext *context);

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

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

Parameters

context

a GOptionContext

 

Since: 2.6


g_option_context_parse ()

gboolean
g_option_context_parse (GOptionContext *context,
                        gint *argc,
                        gchar ***argv,
                        GError **error);

Parses the command line arguments, recognizing options which have been added to context . A side-effect of calling this function is that g_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 g_option_context_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.

Parameters

context

a GOptionContext

 

argc

a pointer to the number of command line arguments.

[inout][optional]

argv

a pointer to the array of command line arguments.

[inout][array length=argc][optional]

error

a return location for errors

 

Returns

TRUE if the parsing was successful, FALSE if an error occurred

Since: 2.6


g_option_context_parse_strv ()

gboolean
g_option_context_parse_strv (GOptionContext *context,
                             gchar ***arguments,
                             GError **error);

Parses the command line arguments.

This function is similar to g_option_context_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 g_free().

On Windows, the strings are expected to be in UTF-8. This is in contrast to g_option_context_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 GOptionContext with GApplication.

Parameters

context

a GOptionContext

 

arguments

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

[inout][array null-terminated=1][optional]

error

a return location for errors

 

Returns

TRUE if the parsing was successful, FALSE if an error occurred

Since: 2.40


g_option_context_set_help_enabled ()

void
g_option_context_set_help_enabled (GOptionContext *context,
                                   gboolean help_enabled);

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

Parameters

context

a GOptionContext

 

help_enabled

TRUE to enable --help, FALSE to disable it

 

Since: 2.6


g_option_context_get_help_enabled ()

gboolean
g_option_context_get_help_enabled (GOptionContext *context);

Returns whether automatic --help generation is turned on for context . See g_option_context_set_help_enabled().

Parameters

context

a GOptionContext

 

Returns

TRUE if automatic help generation is turned on.

Since: 2.6


g_option_context_set_ignore_unknown_options ()

void
g_option_context_set_ignore_unknown_options
                               (GOptionContext *context,
                                gboolean ignore_unknown);

Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the argv array after parsing. By default, g_option_context_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.

Parameters

context

a GOptionContext

 

ignore_unknown

TRUE to ignore unknown options, FALSE to produce an error when unknown options are met

 

Since: 2.6


g_option_context_get_ignore_unknown_options ()

gboolean
g_option_context_get_ignore_unknown_options
                               (GOptionContext *context);

Returns whether unknown options are ignored or not. See g_option_context_set_ignore_unknown_options().

Parameters

context

a GOptionContext

 

Returns

TRUE if unknown options are ignored.

Since: 2.6


g_option_context_get_help ()

gchar *
g_option_context_get_help (GOptionContext *context,
                           gboolean main_help,
                           GOptionGroup *group);

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).

Parameters

context

a GOptionContext

 

main_help

if TRUE, only include the main group

 

group

the GOptionGroup to create help for, or NULL.

[nullable]

Returns

A newly allocated string containing the help text

Since: 2.14


g_option_context_get_strict_posix ()

gboolean
g_option_context_get_strict_posix (GOptionContext *context);

Returns whether strict POSIX code is enabled.

See g_option_context_set_strict_posix() for more information.

Parameters

context

a GOptionContext

 

Returns

TRUE if strict POSIX is enabled, FALSE otherwise.

Since: 2.44


g_option_context_set_strict_posix ()

void
g_option_context_set_strict_posix (GOptionContext *context,
                                   gboolean strict_posix);

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).

Parameters

context

a GOptionContext

 

strict_posix

the new value

 

Since: 2.44


g_option_context_add_main_entries ()

void
g_option_context_add_main_entries (GOptionContext *context,
                                   const GOptionEntry *entries,
                                   const gchar *translation_domain);

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

Parameters

context

a GOptionContext

 

entries

a NULL-terminated array of GOptionEntrys.

[array zero-terminated=1]

translation_domain

a translation domain to use for translating the --help output for the options in entries with gettext(), or NULL.

[nullable]

Since: 2.6


g_option_context_add_group ()

void
g_option_context_add_group (GOptionContext *context,
                            GOptionGroup *group);

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

Parameters

context

a GOptionContext

 

group

the group to add.

[transfer full]

Since: 2.6


g_option_context_set_main_group ()

void
g_option_context_set_main_group (GOptionContext *context,
                                 GOptionGroup *group);

Sets a GOptionGroup as main group of the context . This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating --help output.

Parameters

context

a GOptionContext

 

group

the group to set as main group.

[transfer full]

Since: 2.6


g_option_context_get_main_group ()

GOptionGroup *
g_option_context_get_main_group (GOptionContext *context);

Returns a pointer to the main group of context .

Parameters

context

a GOptionContext

 

Returns

the main group of context , or NULL if context doesn't have a main group. Note that group belongs to context and should not be modified or freed.

[transfer none]

Since: 2.6


g_option_group_new ()

GOptionGroup *
g_option_group_new (const gchar *name,
                    const gchar *description,
                    const gchar *help_description,
                    gpointer user_data,
                    GDestroyNotify destroy);

Creates a new GOptionGroup.

Parameters

name

the name for the option group, this is used to provide help for the options in this group with --help-name

 

description

a description for this group to be shown in --help. This string is translated using the translation domain or translation function of the group

 

help_description

a description for the --help-name option. This string is translated using the translation domain or translation function of the group

 

user_data

user data that will be passed to the pre- and post-parse hooks, the error hook and to callbacks of G_OPTION_ARG_CALLBACK options, or NULL.

[nullable]

destroy

a function that will be called to free user_data , or NULL.

[nullable]

Returns

a newly created option group. It should be added to a GOptionContext or freed with g_option_group_unref().

Since: 2.6


g_option_group_ref ()

GOptionGroup *
g_option_group_ref (GOptionGroup *group);

Increments the reference count of group by one.

Parameters

group

a GOptionGroup

 

Returns

a GOptionGroup

Since: 2.44


g_option_group_unref ()

void
g_option_group_unref (GOptionGroup *group);

Decrements the reference count of group by one. If the reference count drops to 0, the group will be freed. and all memory allocated by the group is released.

Parameters

group

a GOptionGroup

 

Since: 2.44


g_option_group_free ()

void
g_option_group_free (GOptionGroup *group);

g_option_group_free has been deprecated since version 2.44 and should not be used in newly-written code.

Use g_option_group_unref() instead.

Frees a GOptionGroup. Note that you must not free groups which have been added to a GOptionContext.

Parameters

group

a GOptionGroup

 

Since: 2.6


g_option_group_add_entries ()

void
g_option_group_add_entries (GOptionGroup *group,
                            const GOptionEntry *entries);

Adds the options specified in entries to group .

Parameters

group

a GOptionGroup

 

entries

a NULL-terminated array of GOptionEntrys.

[array zero-terminated=1]

Since: 2.6


GOptionParseFunc ()

gboolean
(*GOptionParseFunc) (GOptionContext *context,
                     GOptionGroup *group,
                     gpointer user_data,
                     GError **error);

The type of function that can be called before and after parsing.

Parameters

context

The active GOptionContext

 

group

The group to which the function belongs

 

user_data

User data added to the GOptionGroup containing the option when it was created with g_option_group_new()

 

error

A return location for error details

 

Returns

TRUE if the function completed successfully, FALSE if an error occurred, in which case error should be set with g_set_error()


g_option_group_set_parse_hooks ()

void
g_option_group_set_parse_hooks (GOptionGroup *group,
                                GOptionParseFunc pre_parse_func,
                                GOptionParseFunc post_parse_func);

Associates two functions with group which will be called from g_option_context_parse() before the first option is parsed and after the last option has been parsed, respectively.

Note that the user data to be passed to pre_parse_func and post_parse_func can be specified when constructing the group with g_option_group_new().

Parameters

group

a GOptionGroup

 

pre_parse_func

a function to call before parsing, or NULL.

[nullable]

post_parse_func

a function to call after parsing, or NULL.

[nullable]

Since: 2.6


GOptionErrorFunc ()

void
(*GOptionErrorFunc) (GOptionContext *context,
                     GOptionGroup *group,
                     gpointer user_data,
                     GError **error);

The type of function to be used as callback when a parse error occurs.

Parameters

context

The active GOptionContext

 

group

The group to which the function belongs

 

user_data

User data added to the GOptionGroup containing the option when it was created with g_option_group_new()

 

error

The GError containing details about the parse error

 

g_option_group_set_error_hook ()

void
g_option_group_set_error_hook (GOptionGroup *group,
                               GOptionErrorFunc error_func);

Associates a function with group which will be called from g_option_context_parse() when an error occurs.

Note that the user data to be passed to error_func can be specified when constructing the group with g_option_group_new().

Parameters

group

a GOptionGroup

 

error_func

a function to call when an error occurs

 

Since: 2.6


g_option_group_set_translate_func ()

void
g_option_group_set_translate_func (GOptionGroup *group,
                                   GTranslateFunc func,
                                   gpointer data,
                                   GDestroyNotify destroy_notify);

Sets the function which is used to translate user-visible strings, for --help output. Different groups can use different GTranslateFuncs. If func is NULL, strings are not translated.

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

Parameters

group

a GOptionGroup

 

func

the GTranslateFunc, or NULL.

[nullable]

data

user data to pass to func , or NULL.

[nullable]

destroy_notify

a function which gets called to free data , or NULL.

[nullable]

Since: 2.6


g_option_group_set_translation_domain ()

void
g_option_group_set_translation_domain (GOptionGroup *group,
                                       const gchar *domain);

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

Parameters

group

a GOptionGroup

 

domain

the domain to use

 

Since: 2.6

Types and Values

enum GOptionError

Error codes returned by option parsing.

Members

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.

 

G_OPTION_ERROR

#define G_OPTION_ERROR (g_option_error_quark ())

Error domain for option parsing. Errors in this domain will be from the GOptionError enumeration. See GError for information on error domains.


GOptionContext

typedef struct _GOptionContext GOptionContext;

A GOptionContext struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.


enum GOptionArg

The GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: -x arg, with a long option: --name arg or combined in a single argument: --name=arg.

Members

G_OPTION_ARG_NONE

No extra argument. This is useful for simple flags or booleans.

 

G_OPTION_ARG_STRING

The option takes a UTF-8 string argument.

 

G_OPTION_ARG_INT

The option takes an integer argument.

 

G_OPTION_ARG_CALLBACK

The option provides a callback (of type GOptionArgFunc) to parse the extra argument.

 

G_OPTION_ARG_FILENAME

The option takes a filename as argument, which will be in the GLib filename encoding rather than UTF-8.

 

G_OPTION_ARG_STRING_ARRAY

The option takes a string argument, multiple uses of the option are collected into an array of strings.

 

G_OPTION_ARG_FILENAME_ARRAY

The option takes a filename as argument, multiple uses of the option are collected into an array of strings.

 

G_OPTION_ARG_DOUBLE

The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12

 

G_OPTION_ARG_INT64

The option takes a 64-bit integer. Like G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with 0x, for example, 0xffffffff). Since 2.12

 

enum GOptionFlags

Flags which modify individual options.

Members

G_OPTION_FLAG_NONE

No flags. Since: 2.42.

 

G_OPTION_FLAG_HIDDEN

The option doesn't appear in --help output.

 

G_OPTION_FLAG_IN_MAIN

The option appears in the main section of the --help output, even if it is defined in a group.

 

G_OPTION_FLAG_REVERSE

For options of the G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. i.e. FALSE will be stored into the argument rather than TRUE.

 

G_OPTION_FLAG_NO_ARG

For options of the G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a G_OPTION_ARG_NONE option). Since 2.8

 

G_OPTION_FLAG_FILENAME

For options of the G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8

 

G_OPTION_FLAG_OPTIONAL_ARG

For options of the G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of GOptionParseFunc will be set to NULL. Since 2.8

 

G_OPTION_FLAG_NOALIAS

This flag turns off the automatic conflict resolution which prefixes long option names with groupname- if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8.

 

G_OPTION_REMAINING

#define G_OPTION_REMAINING ""

If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in argv. The option must be of type G_OPTION_ARG_CALLBACK, G_OPTION_ARG_STRING_ARRAY or G_OPTION_ARG_FILENAME_ARRAY.

Using G_OPTION_REMAINING instead of simply scanning argv for leftover arguments has the advantage that GOption takes care of necessary encoding conversions for strings or filenames.

Since: 2.6


struct GOptionEntry

struct GOptionEntry {
  const gchar *long_name;
  gchar        short_name;
  gint         flags;

  GOptionArg   arg;
  gpointer     arg_data;

  const gchar *description;
  const gchar *arg_description;
};

A GOptionEntry struct defines a single option. To have an effect, they must be added to a GOptionGroup with g_option_context_add_main_entries() or g_option_group_add_entries().

Members

const gchar *long_name;

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name.

 

gchar short_name;

If an option has a short name, it can be specified -short_name in a commandline. short_name must be a printable ASCII character different from '-', or zero if the option has no short name.

 

gint flags;

Flags from GOptionFlags

 

GOptionArg arg;

The type of the option, as a GOptionArg

 

gpointer arg_data;

If the arg type is G_OPTION_ARG_CALLBACK, then arg_data must point to a GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, arg_data is a pointer to a location to store the value, the required type of the location depends on the arg type:

 

const gchar *description;

the description for the option in --help output. The description is translated using the translate_func of the group, see g_option_group_set_translation_domain().

 

const gchar *arg_description;

The placeholder to use for the extra argument parsed by the option in --help output. The arg_description is translated using the translate_func of the group, see g_option_group_set_translation_domain().

 

G_OPTION_ENTRY_NULL

#define             G_OPTION_ENTRY_NULL

A GOptionEntry array requires a NULL terminator, this macro can be used as terminator instead of an explicit { 0 } but it cannot be assigned to a variable.

1
GOptionEntry option[] = { G_OPTION_ENTRY_NULL };

Since: 2.70


GOptionGroup

typedef struct _GOptionGroup GOptionGroup;

A GOptionGroup struct defines the options in a single group. The struct has only private fields and should not be directly accessed.

All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a GOptionGroup holding their options, which the application can then add to its GOptionContext.