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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
Title: Commandline Option Parser
# Commandline Option Parser
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 [method@GLib.OptionContext.set_help_enabled], GOption will recognize
the `--help`, `-?`, `--help-all` and `--help-groupname` options (where `groupname`
is the name of a [struct@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 [struct@GLib.OptionGroup]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 [method@GLib.OptionContext.parse].
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 [method@GLib.OptionContext.parse]
Here is a complete example of setting up GOption to parse the example
commandline above and produce the example help output.
```c
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
[struct@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
[method@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 #GOptionContext directly
in order to correctly deal with Unicode filenames on Windows:
```c
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);
...
}
```
|
