From: Stefan Kost Date: Tue, 14 Apr 2009 08:23:25 +0000 (+0300) Subject: goption: move docs from tmpl folder to inline comments X-Git-Tag: 2.21.0~34 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=2026c232b3437ff0f1222b6b045379ca273393e8;p=platform%2Fupstream%2Fglib.git goption: move docs from tmpl folder to inline comments --- diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore new file mode 100644 index 0000000..527668d --- /dev/null +++ b/docs/reference/glib/tmpl/.gitignore @@ -0,0 +1 @@ +option.sgml diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml deleted file mode 100644 index 30757bc..0000000 --- a/docs/reference/glib/tmpl/option.sgml +++ /dev/null @@ -1,603 +0,0 @@ - -Commandline option parser - - -parses commandline options - - - -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. - - - 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 -, , -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. - - - -Usage: - testtreemodel [OPTION...] - test tree model performance - -Help Options: - -?, --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. - - -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; - 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); - } - - /* ... */ - -} - - - - - - - - - - - - -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_FAILED: A #GOptionArgFunc callback failed. - - - -Error domain for option parsing. Errors in this domain will -be from the #GOptionError enumeration. See #GError for information on -error domains. - - - - - - -The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK -options. - - -@option_name: The name of the option being parsed. This will be either a - single dash followed by a single letter (for a short name) or two dashes - followed by a long option name. -@value: The value to be parsed. -@data: User data added to the #GOptionGroup containing the option when it - was created with g_option_group_new() -@error: A return location for errors. The error code %G_OPTION_ERROR_FAILED - is intended to be used for errors in #GOptionArgFunc callbacks. -@Returns: %TRUE if the option was successfully parsed, %FALSE if an error - occurred, in which case @error should be set with g_set_error() - - - - -A GOptionContext struct defines which options -are accepted by the commandline option parser. The struct has only private -fields and should not be directly accessed. - - - - - - - - -@parameter_string: -@Returns: - - - - - - - -@context: -@summary: - - - - - - - -@context: -@Returns: - - - - - - - -@context: -@description: - - - - - - - -@context: -@Returns: - - - - -The type of functions which are used to translate user-visible -strings, for output. - - -@str: the untranslated string -@data: user data specified when installing the function, e.g. - in g_option_group_set_translate_func() -@Returns: a translation of the string for the current locale. - The returned string is owned by GLib and must not be freed. - - - - - - - -@context: -@func: -@data: -@destroy_notify: - - - - - - - -@context: -@domain: - - - - - - - -@context: - - - - - - - -@context: -@argc: -@argv: -@error: -@Returns: - - - - - - - -@context: -@help_enabled: - - - - - - - -@context: -@Returns: - - - - - - - -@context: -@ignore_unknown: - - - - - - - -@context: -@Returns: - - - - - - - -@context: -@main_help: -@group: -@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. -@G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument - can be formatted either for the user's locale or for the "C" locale. Since 2.12 -@G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT - but for larger numbers. The number can be in decimal base, or in hexadecimal - (when prefixed with 0x, for example, 0xffffffff). - Since 2.12 - - - -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. -@G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag - indicates that the sense of the option is reversed. -@G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, - this flag indicates that the callback does not take any argument - (like a %G_OPTION_ARG_NONE option). Since 2.8 -@G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument should be passed to the - callback in the GLib filename encoding rather than UTF-8. Since 2.8 -@G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument supply is optional. If no argument - is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 -@G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution - which prefixes long option names with groupname- if - there is a conflict. This option should only be used in situations where - aliasing is necessary to model some legacy commandline interface. It is - not safe to use this option, unless all option groups are under your - direct control. Since 2.8. - - - -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_CALLBACK, %G_OPTION_ARG_STRING_ARRAY -or %G_OPTION_ARG_FILENAME_ARRAY. - - - -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. - - -@Since: 2.6 - - - - -A GOptionEntry defines a single option. -To have an effect, they must be added to a #GOptionGroup with -g_option_context_add_main_entries() or g_option_group_add_entries(). - - -@long_name: The long name of an option can be used to specify it - in a commandline as --long_name. Every - option must have a long name. To resolve conflicts if multiple - option groups contain the same long name, it is also possible to - specify the option as - --groupname-long_name. -@short_name: If an option has a short name, it can be specified - -short_name in a commandline. @short_name must be - a printable ASCII character different from '-', or zero if the option has no - short name. -@flags: Flags from #GOptionFlags. -@arg: The type of the option, as a #GOptionArg. -@arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must - point to a #GOptionArgFunc callback function, which will be called to handle - the extra argument. Otherwise, @arg_data is a pointer to a location to store - the value, the required type of the location depends on the @arg type: - - - %G_OPTION_ARG_NONE - %gboolean - - - %G_OPTION_ARG_STRING - %gchar* - - - %G_OPTION_ARG_INT - %gint - - - %G_OPTION_ARG_FILENAME - %gchar* - - - %G_OPTION_ARG_STRING_ARRAY - %gchar** - - - %G_OPTION_ARG_FILENAME_ARRAY - %gchar** - - - %G_OPTION_ARG_DOUBLE - %gdouble - - -@description: the description for the option in - output. The @description is translated using the @translate_func of the - group, see g_option_group_set_translation_domain(). -@arg_description: The placeholder to use for the extra argument parsed - by the option in - output. The @arg_description is translated using the @translate_func of the - group, see g_option_group_set_translation_domain(). - - - - - - -@context: -@entries: -@translation_domain: - - - - -A GOptionGroup struct defines the options in a single -group. The struct has only private fields and should not be directly accessed. - - -All options in a group share the same translation function. Libaries which -need to parse commandline options are expected to provide a function for -getting a GOptionGroup holding their options, which -the application can then add to its #GOptionContext. - - - - - - - - -@context: -@group: - - - - - - - -@context: -@group: - - - - - - - -@context: -@Returns: - - - - - - - -@name: -@description: -@help_description: -@user_data: -@destroy: -@Returns: - - - - - - - -@group: - - - - - - - -@group: -@entries: - - - - -The type of function that can be called before and after parsing. - - -@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() -@error: A return location for error details -@Returns: %TRUE if the function completed successfully, %FALSE if an error - occurred, in which case @error should be set with g_set_error() - - - - - - - -@group: -@pre_parse_func: -@post_parse_func: - - - - -The type of function to be used as callback when a parse error occurs. - - -@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() -@error: The #GError containing details about the parse error - - - - - - - -@group: -@error_func: - - - - - - - -@group: -@func: -@data: -@destroy_notify: - - - - - - - -@group: -@domain: - - diff --git a/glib/goption.c b/glib/goption.c index fa39b79..633ad2e 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -18,6 +18,119 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:option + * @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. + * + * 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 + * , , + * 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. + * + * + * + * Usage: + * testtreemodel [OPTION...] - test tree model performance + * + * Help Options: + * -?, --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. + * + * + * 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; + * 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); + * } + * + * // ... + * + * } + * + */ #include "config.h" diff --git a/glib/goption.h b/glib/goption.h index 86fc0cd..0743e76 100644 --- a/glib/goption.h +++ b/glib/goption.h @@ -30,10 +30,55 @@ G_BEGIN_DECLS +/** + * GOptionContext: + * + * A GOptionContext struct defines which options + * are accepted by the commandline option parser. The struct has only private + * fields and should not be directly accessed. + */ typedef struct _GOptionContext GOptionContext; + +/** + * GOptionGroup: + * + * A GOptionGroup struct defines the options in a single + * group. The struct has only private fields and should not be directly accessed. + * + * All options in a group share the same translation function. Libaries which + * need to parse commandline options are expected to provide a function for + * getting a GOptionGroup holding their options, which + * the application can then add to its #GOptionContext. + */ typedef struct _GOptionGroup GOptionGroup; typedef struct _GOptionEntry GOptionEntry; +/** + * GOptionFlags: + * @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. + * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag + * indicates that the sense of the option is reversed. + * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, + * this flag indicates that the callback does not take any argument + * (like a %G_OPTION_ARG_NONE option). Since 2.8 + * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK + * kind, this flag indicates that the argument should be passed to the + * callback in the GLib filename encoding rather than UTF-8. Since 2.8 + * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK + * kind, this flag indicates that the argument supply is optional. If no argument + * is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 + * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution + * which prefixes long option names with groupname- if + * there is a conflict. This option should only be used in situations where + * aliasing is necessary to model some legacy commandline interface. It is + * not safe to use this option, unless all option groups are under your + * direct control. Since 2.8. + * + * Flags which modify individual options. + */ typedef enum { G_OPTION_FLAG_HIDDEN = 1 << 0, @@ -45,6 +90,31 @@ typedef enum G_OPTION_FLAG_NOALIAS = 1 << 6 } GOptionFlags; +/** + * GOptionArg: + * @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. + * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument + * can be formatted either for the user's locale or for the "C" locale. Since 2.12 + * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT + * but for larger numbers. The number can be in decimal base, or in hexadecimal + * (when prefixed with 0x, for example, 0xffffffff). + * Since 2.12 + * + * 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: . + */ typedef enum { G_OPTION_ARG_NONE, @@ -58,23 +128,80 @@ typedef enum G_OPTION_ARG_INT64 } GOptionArg; +/** + * GOptionArgFunc: + * @option_name: The name of the option being parsed. This will be either a + * single dash followed by a single letter (for a short name) or two dashes + * followed by a long option name. + * @value: The value to be parsed. + * @data: User data added to the #GOptionGroup containing the option when it + * was created with g_option_group_new() + * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED + * is intended to be used for errors in #GOptionArgFunc callbacks. + * + * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK + * options. + * + * Returns: %TRUE if the option was successfully parsed, %FALSE if an error + * occurred, in which case @error should be set with g_set_error() + */ typedef gboolean (*GOptionArgFunc) (const gchar *option_name, const gchar *value, gpointer data, GError **error); +/** + * GOptionParseFunc: + * @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() + * @error: A return location for error details + * + * The type of function that can be called before and after parsing. + * + * Returns: %TRUE if the function completed successfully, %FALSE if an error + * occurred, in which case @error should be set with g_set_error() + */ typedef gboolean (*GOptionParseFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); +/** + * GOptionErrorFunc: + * @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() + * @error: The #GError containing details about the parse error + * + * The type of function to be used as callback when a parse error occurs. + */ typedef void (*GOptionErrorFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); +/** + * G_OPTION_ERROR: + * + * Error domain for option parsing. Errors in this domain will + * be from the #GOptionError enumeration. See #GError for information on + * error domains. + */ #define G_OPTION_ERROR (g_option_error_quark ()) +/** + * GOptionError: + * @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_FAILED: A #GOptionArgFunc callback failed. + * + * Error codes returned by option parsing. + */ typedef enum { G_OPTION_ERROR_UNKNOWN_OPTION, @@ -84,7 +211,66 @@ typedef enum GQuark g_option_error_quark (void); - +/** + * GOptionEntry: + * @long_name: The long name of an option can be used to specify it + * in a commandline as --long_name. Every + * option must have a long name. To resolve conflicts if multiple + * option groups contain the same long name, it is also possible to + * specify the option as + * --groupname-long_name. + * @short_name: If an option has a short name, it can be specified + * -short_name in a commandline. @short_name must be + * a printable ASCII character different from '-', or zero if the option has no + * short name. + * @flags: Flags from #GOptionFlags. + * @arg: The type of the option, as a #GOptionArg. + * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must + * point to a #GOptionArgFunc callback function, which will be called to handle + * the extra argument. Otherwise, @arg_data is a pointer to a location to store + * the value, the required type of the location depends on the @arg type: + * + * + * %G_OPTION_ARG_NONE + * %gboolean + * + * + * %G_OPTION_ARG_STRING + * %gchar* + * + * + * %G_OPTION_ARG_INT + * %gint + * + * + * %G_OPTION_ARG_FILENAME + * %gchar* + * + * + * %G_OPTION_ARG_STRING_ARRAY + * %gchar** + * + * + * %G_OPTION_ARG_FILENAME_ARRAY + * %gchar** + * + * + * %G_OPTION_ARG_DOUBLE + * %gdouble + * + * + * @description: the description for the option in + * output. The @description is translated using the @translate_func of the + * group, see g_option_group_set_translation_domain(). + * @arg_description: The placeholder to use for the extra argument parsed + * by the option in + * output. The @arg_description is translated using the @translate_func of the + * group, see g_option_group_set_translation_domain(). + * + * A GOptionEntry defines a single option. + * To have an effect, they must be added to a #GOptionGroup with + * g_option_context_add_main_entries() or g_option_group_add_entries(). + */ struct _GOptionEntry { const gchar *long_name; @@ -98,6 +284,22 @@ struct _GOptionEntry const gchar *arg_description; }; +/** + * G_OPTION_REMAINING: + * + * 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_CALLBACK, %G_OPTION_ARG_STRING_ARRAY + * or %G_OPTION_ARG_FILENAME_ARRAY. + * + * + * 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. + * + * Since: 2.6 + */ #define G_OPTION_REMAINING "" GOptionContext *g_option_context_new (const gchar *parameter_string); diff --git a/glib/gtypes.h b/glib/gtypes.h index 56cc648..571a7db 100644 --- a/glib/gtypes.h +++ b/glib/gtypes.h @@ -92,6 +92,19 @@ typedef void (*GHFunc) (gpointer key, gpointer value, gpointer user_data); typedef void (*GFreeFunc) (gpointer data); + +/** + * GTranslateFunc: + * @str: the untranslated string + * @data: user data specified when installing the function, e.g. + * in g_option_group_set_translate_func() + * + * The type of functions which are used to translate user-visible + * strings, for output. + * + * Returns: a translation of the string for the current locale. + * The returned string is owned by GLib and must not be freed. + */ typedef const gchar * (*GTranslateFunc) (const gchar *str, gpointer data);