diff --git a/ChangeLog b/ChangeLog index 1542390c8..a21e9a456 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/goption.c: Doc additions. + * glib/goption.c (parse_arg): Convert filenames to UTF-8 on Windows. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 1542390c8..a21e9a456 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/goption.c: Doc additions. + * glib/goption.c (parse_arg): Convert filenames to UTF-8 on Windows. diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 1542390c8..a21e9a456 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/goption.c: Doc additions. + * glib/goption.c (parse_arg): Convert filenames to UTF-8 on Windows. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 1542390c8..a21e9a456 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/goption.c: Doc additions. + * glib/goption.c (parse_arg): Convert filenames to UTF-8 on Windows. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 1542390c8..a21e9a456 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/goption.c: Doc additions. + * glib/goption.c (parse_arg): Convert filenames to UTF-8 on Windows. diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 9fd67d467..fa8c45bd1 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,7 @@ 2004-10-29 Matthias Clasen + * glib/tmpl/option.sgml: Add an example. + * glib/glib-sections.txt: Add G_OPTION_REMAINING * glib/tmpl/option.sgml: Add docs. diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml index 2b2cae594..2a92f7a7b 100644 --- a/docs/reference/glib/tmpl/option.sgml +++ b/docs/reference/glib/tmpl/option.sgml @@ -12,7 +12,7 @@ following example: -test -x 1 --long-y foo --flag --long-z=baz -uvw -- file1 file2 +testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2 @@ -46,9 +46,9 @@ Another important feature of GOption is that it can automatically generate nicel formatted help output. Unless it is explicitly turned off with g_option_context_set_help_enabled(), GOption will recognize the , , -and 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. +and 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. @@ -64,6 +64,9 @@ 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 @@ -80,12 +83,47 @@ care of converting it to the right encoding; strings are returned in UTF-8, filenames are returned in the GLib filename encoding. + +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; + + context = g_option_context_new ("[OPTION...]"); + g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); + g_option_context_add_group (context, gtk_get_option_group (TRUE)); + g_option_context_parse (context, &argc, &argv, &error); + + /* ... */ + +} + + - Error codes returned by option parsing. @@ -94,10 +132,9 @@ Error codes returned by option parsing. @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_BAD_VALUE: A value couldn't be parsed. @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. - Error domain for option parsing. Errors in this domain will @@ -106,36 +143,6 @@ error domains. - - -Flags which modify individual options. - - -@G_OPTION_FLAG_HIDDEN: The option doesn't appear in - output. -@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the - output, even if it is defined in a group. - - - - -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: -, with a long option: -or combined in a single argument: . - - -@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. -@G_OPTION_ARG_STRING: The option takes a string argument. -@G_OPTION_ARG_INT: The option takes an integer argument. -@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the - extra argument. -@G_OPTION_ARG_FILENAME: The option takes a filename as argument. -@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. @@ -228,6 +235,36 @@ fields and should not be directly accessed. @Returns: + + +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: +, with a long option: +or combined in a single argument: . + + +@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. +@G_OPTION_ARG_STRING: The option takes a string argument. +@G_OPTION_ARG_INT: The option takes an integer argument. +@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the + extra argument. +@G_OPTION_ARG_FILENAME: The option takes a filename as argument. +@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. + + + +Flags which modify individual options. + + +@G_OPTION_FLAG_HIDDEN: The option doesn't appear in + output. +@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the + output, even if it is defined in a group. + If a long option in the main group has this name, it is not treated as a @@ -256,7 +293,7 @@ g_option_context_add_main_entries() or g_option_group_add_entries(). in a commandline as --long_name. Every option must have a long name. @short_name: If an option has a short name, it can be specified - -short_name in a commandline. + -short_name in a commandline. @flags: Flags from #GOptionEntryFlags. @arg: The type of the option, as a #GOptionArg. @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must @@ -382,7 +419,9 @@ the application can then add to its #GOptionContext. The type of function that can be called before and after parsing. -@context The active #GOptionContext +@context The active #GOptionContext + +@context: @group: The group to which the function belongs @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() @@ -390,6 +429,7 @@ The type of function that can be called before and after parsing. @Returns: %TRUE if the function completed successfully, %FALSE if an error occurred + @@ -406,7 +446,9 @@ The type of function to be used as callback when a parse error occurs. -@context The active #GOptionContext +@context The active #GOptionContext + +@context: @group: The group to which the function belongs @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() diff --git a/glib/goption.c b/glib/goption.c index 5905382ff..b40afb2f7 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -221,7 +221,8 @@ g_option_context_get_help_enabled (GOptionContext *context) * 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). + * 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 **/