From eca5c5ea7decc3950a5eb759f97924dbb4526441 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 29 Oct 2004 20:26:19 +0000 Subject: [PATCH] Update. --- docs/reference/glib/tmpl/option.sgml | 84 +++++++++++++++++----------- 1 file changed, 51 insertions(+), 33 deletions(-) diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml index ed43fdf7..2b2cae59 100644 --- a/docs/reference/glib/tmpl/option.sgml +++ b/docs/reference/glib/tmpl/option.sgml @@ -30,9 +30,13 @@ The example demonstrates a number of features of the GOption commandline parser 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 are returned to the application as rest arguments. + arguments (even those starting with a dash) are returned to the application as rest + arguments. @@ -81,6 +85,7 @@ filenames are returned in the GLib filename encoding. + Error codes returned by option parsing. @@ -89,9 +94,10 @@ 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 @@ -100,6 +106,36 @@ 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. @@ -192,35 +228,22 @@ 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: . +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_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY. -@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. +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. -@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. +@Since: 2.6 + @@ -233,7 +256,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 @@ -359,9 +382,7 @@ 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: +@context The active #GOptionContext @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() @@ -369,7 +390,6 @@ The type of function that can be called before and after parsing. @Returns: %TRUE if the function completed successfully, %FALSE if an error occurred - @@ -386,9 +406,7 @@ The type of function to be used as callback when a parse error occurs. -@context The active #GOptionContext - -@context: +@context The active #GOptionContext @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() -- 2.34.1