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.
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.
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:
Functions
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.
Since: 2.6
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()).
Since: 2.12
GTranslateFunc ()
const gchar *
(*GTranslateFunc) (const gchar *str,
gpointer data);
The type of functions which are used to translate user-visible
strings, for <option>--help</option> output.
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_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.
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).
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.
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.
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.
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.
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).
Returns
A newly allocated string containing the help text
Since: 2.14
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).
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.
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.
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.
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
.
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_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.
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.
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
.
Since: 2.6
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().
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.
Since: 2.6