![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> enum GOptionError; #define G_OPTION_ERROR gboolean (*GOptionArgFunc) (const gchar *option_name, const gchar *value, gpointer data, GError **error); GOptionContext; GOptionContext * g_option_context_new (const gchar *parameter_string); void g_option_context_set_summary (GOptionContext *context, const gchar *summary); const gchar * g_option_context_get_summary (GOptionContext *context); void g_option_context_set_description (GOptionContext *context, const gchar *description); const gchar * g_option_context_get_description (GOptionContext *context); const gchar * (*GTranslateFunc) (const gchar *str, gpointer data); void g_option_context_set_translate_func (GOptionContext *context, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify); void g_option_context_set_translation_domain (GOptionContext *context, const gchar *domain); void g_option_context_free (GOptionContext *context); gboolean g_option_context_parse (GOptionContext *context, gint *argc, gchar ***argv, GError **error); void g_option_context_set_help_enabled (GOptionContext *context, gboolean help_enabled); gboolean g_option_context_get_help_enabled (GOptionContext *context); void g_option_context_set_ignore_unknown_options (GOptionContext *context, gboolean ignore_unknown); gboolean g_option_context_get_ignore_unknown_options (GOptionContext *context); gchar * g_option_context_get_help (GOptionContext *context, gboolean main_help, GOptionGroup *group); enum GOptionArg; enum GOptionFlags; #define G_OPTION_REMAINING GOptionEntry; void g_option_context_add_main_entries (GOptionContext *context, const GOptionEntry *entries, const gchar *translation_domain); GOptionGroup; void g_option_context_add_group (GOptionContext *context, GOptionGroup *group); void g_option_context_set_main_group (GOptionContext *context, GOptionGroup *group); GOptionGroup * g_option_context_get_main_group (GOptionContext *context); GOptionGroup * g_option_group_new (const gchar *name, const gchar *description, const gchar *help_description, gpointer user_data, GDestroyNotify destroy); void g_option_group_free (GOptionGroup *group); void g_option_group_add_entries (GOptionGroup *group, const GOptionEntry *entries); gboolean (*GOptionParseFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); void g_option_group_set_parse_hooks (GOptionGroup *group, GOptionParseFunc pre_parse_func, GOptionParseFunc post_parse_func); void (*GOptionErrorFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); void g_option_group_set_error_hook (GOptionGroup *group, GOptionErrorFunc error_func); void g_option_group_set_translate_func (GOptionGroup *group, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify); void g_option_group_set_translation_domain (GOptionGroup *group, const gchar *domain);
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.
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.
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
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.
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, &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, &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, &argc, &argv, &error)) { g_print ("option parsing failed: %s\n", error->message); exit (1); } /* ... */ }
typedef enum { G_OPTION_ERROR_UNKNOWN_OPTION, G_OPTION_ERROR_BAD_VALUE, G_OPTION_ERROR_FAILED } GOptionError;
Error codes returned by option parsing.
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() .
|
|
A value couldn't be parsed. | |
A GOptionArgFunc callback failed. |
#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.
gboolean (*GOptionArgFunc) (const gchar *option_name, const gchar *value, gpointer data, GError **error);
The type of function to be passed as callback for G_OPTION_ARG_CALLBACK
options.
|
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. |
|
The value to be parsed. |
|
User data added to the GOptionGroup containing the option when it
was created with g_option_group_new()
|
|
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()
|
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.
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.
|
a string which is displayed in
the first line of --help output, after the
usage summary
|
Returns : |
a newly created GOptionContext, which must be
freed with g_option_context_free() after use.
|
Since 2.6
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()
).
|
a GOptionContext |
|
a string to be shown in --help output
before the list of options, or NULL
|
Since 2.12
const gchar * g_option_context_get_summary (GOptionContext *context);
Returns the summary. See g_option_context_set_summary()
.
|
a GOptionContext |
Returns : |
the summary |
Since 2.12
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()
).
|
a GOptionContext |
|
a string to be shown in --help output
after the list of options, or NULL
|
Since 2.12
const gchar * g_option_context_get_description (GOptionContext *context);
Returns the description. See g_option_context_set_description()
.
|
a GOptionContext |
Returns : |
the description |
Since 2.12
const gchar * (*GTranslateFunc) (const gchar *str, gpointer data);
The type of functions which are used to translate user-visible
strings, for --help
output.
|
the untranslated string |
|
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. |
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()
.
|
a GOptionContext |
|
the GTranslateFunc, or NULL
|
|
user data to pass to func , or NULL
|
|
a function which gets called to free data , or NULL
|
Since 2.12
void g_option_context_set_translation_domain (GOptionContext *context, const gchar *domain);
A convenience function to use gettext()
for translating
user-visible strings.
|
a GOptionContext |
|
the domain to use |
Since 2.12
void g_option_context_free (GOptionContext *context);
Frees context and all the groups which have been added to it.
|
a GOptionContext |
Since 2.6
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.
|
a GOptionContext |
|
a pointer to the number of command line arguments |
|
a pointer to the array of command line arguments |
|
a return location for errors |
Returns : |
TRUE if the parsing was successful,
FALSE if an error occurred
|
Since 2.6
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
, -?
, --help-all
and --help-
groupname
and creates
suitable output to stdout.
|
a GOptionContext |
|
TRUE to enable --help , FALSE to disable it
|
Since 2.6
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()
.
|
a GOptionContext |
Returns : |
TRUE if automatic help generation is turned on.
|
Since 2.6
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.
|
a GOptionContext |
|
TRUE to ignore unknown options, FALSE to produce
an error when unknown options are met
|
Since 2.6
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()
.
|
a GOptionContext |
Returns : |
TRUE if unknown options are ignored.
|
Since 2.6
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)
.
|
a GOptionContext |
|
if TRUE , only include the main group
|
|
the GOptionGroup to create help for, or NULL
|
Returns : |
A newly allocated string containing the help text |
Since 2.14
typedef enum { G_OPTION_ARG_NONE, G_OPTION_ARG_STRING, G_OPTION_ARG_INT, G_OPTION_ARG_CALLBACK, G_OPTION_ARG_FILENAME, G_OPTION_ARG_STRING_ARRAY, G_OPTION_ARG_FILENAME_ARRAY, G_OPTION_ARG_DOUBLE, G_OPTION_ARG_INT64 } 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
.
No extra argument. This is useful for simple flags. | |
The option takes a string argument. | |
The option takes an integer argument. | |
The option provides a callback to parse the extra argument. | |
The option takes a filename as argument. | |
The option takes a string argument, multiple uses of the option are collected into an array of strings. | |
The option takes a filename as argument, multiple uses of the option are collected into an array of strings. | |
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 | |
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
|
typedef enum { G_OPTION_FLAG_HIDDEN = 1 << 0, G_OPTION_FLAG_IN_MAIN = 1 << 1, G_OPTION_FLAG_REVERSE = 1 << 2, G_OPTION_FLAG_NO_ARG = 1 << 3, G_OPTION_FLAG_FILENAME = 1 << 4, G_OPTION_FLAG_OPTIONAL_ARG = 1 << 5, G_OPTION_FLAG_NOALIAS = 1 << 6 } GOptionFlags;
Flags which modify individual options.
The option doesn't appear in --help
output.
|
|
The option appears in the main section of the
--help output, even if it is defined in a group.
|
|
For options of the G_OPTION_ARG_NONE kind, this flag
indicates that the sense of the option is reversed.
|
|
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
|
|
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
|
|
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
|
|
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.
|
#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
typedef struct { const gchar *long_name; gchar short_name; gint flags; GOptionArg arg; gpointer arg_data; const gchar *description; const gchar *arg_description; } GOptionEntry;
A GOptionEntry 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()
.
const gchar * |
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 |
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 from GOptionFlags. |
GOptionArg |
The type of the option, as a GOptionArg. |
gpointer |
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 * |
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 * |
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() .
|
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.
|
a GOptionContext |
|
a NULL -terminated array of GOptionEntrys
|
|
a translation domain to use for translating
the --help output for the options in entries
with gettext() , or NULL
|
Since 2.6
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. Libaries 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.
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 the group will
be freed together with the context when g_option_context_free()
is
called, so you must not free the group yourself after adding it
to a context.
|
a GOptionContext |
|
the group to add |
Since 2.6
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.
|
a GOptionContext |
|
the group to set as main group |
Since 2.6
GOptionGroup * g_option_context_get_main_group (GOptionContext *context);
Returns a pointer to the main group of 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.
|
Since 2.6
GOptionGroup * g_option_group_new (const gchar *name, const gchar *description, const gchar *help_description, gpointer user_data, GDestroyNotify destroy);
Creates a new GOptionGroup.
|
the name for the option group, this is used to provide
help for the options in this group with --help- name
|
|
a description for this group to be shown in
--help . This string is translated using the translation
domain or translation function of the group
|
|
a description for the --help- name option.
This string is translated using the translation domain or translation function
of the group
|
|
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
|
|
a function that will be called to free user_data , or NULL
|
Returns : |
a newly created option group. It should be added
to a GOptionContext or freed with g_option_group_free() .
|
Since 2.6
void g_option_group_free (GOptionGroup *group);
Frees a GOptionGroup. Note that you must not free groups which have been added to a GOptionContext.
|
a GOptionGroup |
Since 2.6
void g_option_group_add_entries (GOptionGroup *group, const GOptionEntry *entries);
Adds the options specified in entries
to group
.
|
a GOptionGroup |
|
a NULL -terminated array of GOptionEntrys
|
Since 2.6
gboolean (*GOptionParseFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error);
The type of function that can be called before and after parsing.
|
The active GOptionContext |
|
The group to which the function belongs |
|
User data added to the GOptionGroup containing the option when it
was created with g_option_group_new()
|
|
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()
|
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()
.
|
a GOptionGroup |
|
a function to call before parsing, or NULL
|
|
a function to call after parsing, or NULL
|
Since 2.6
void (*GOptionErrorFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error);
The type of function to be used as callback when a parse error occurs.
|
The active GOptionContext |
|
The group to which the function belongs |
|
User data added to the GOptionGroup containing the option when it
was created with g_option_group_new()
|
|
The GError containing details about the parse error |
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()
.
|
a GOptionGroup |
|
a function to call when an error occurs |
Since 2.6
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()
.
|
a GOptionGroup |
|
the GTranslateFunc, or NULL
|
|
user data to pass to func , or NULL
|
|
a function which gets called to free data , or NULL
|
Since 2.6
void g_option_group_set_translation_domain (GOptionGroup *group, const gchar *domain);
A convenience function to use gettext()
for translating
user-visible strings.
|
a GOptionGroup |
|
the domain to use |
Since 2.6