mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-25 15:06:14 +01:00
docs: Move the GOption SECTION
Move the content to the new goption.md file. Helps: #3037
This commit is contained in:
Matthias Clasen
Philip Withnall
parent
8b9c4cfb87
commit
ab066d4856
@ -63,6 +63,7 @@ content_files = [
|
||||
"testing.md",
|
||||
"threads.md",
|
||||
"markup.md",
|
||||
"goption.md",
|
||||
]
|
||||
content_images = [
|
||||
"file-name-encodings.png",
|
||||
|
||||
149
docs/reference/glib/goption.md
Normal file
149
docs/reference/glib/goption.md
Normal file
@ -0,0 +1,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);
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
@ -161,6 +161,7 @@ expand_content_files = [
|
||||
'testing.md',
|
||||
'threads.md',
|
||||
'markup.md',
|
||||
'goption.md',
|
||||
]
|
||||
|
||||
glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'
|
||||
|
||||
160
glib/goption.c
160
glib/goption.c
@ -19,166 +19,6 @@
|
||||
* along with this library; if not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
/**
|
||||
* SECTION:goptioncontext
|
||||
* @Short_description: parses commandline options
|
||||
* @Title: 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 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:
|
||||
* -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.
|
||||
* |[<!-- language="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
|
||||
* #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:
|
||||
*
|
||||
* |[<!-- language="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);
|
||||
*
|
||||
* ...
|
||||
* }
|
||||
* ]|
|
||||
*/
|
||||
|
||||
#include "config.h"
|
||||
|
||||
#include <string.h>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user