From: Matthias Clasen Date: Fri, 29 Oct 2004 18:43:34 +0000 (+0000) Subject: Document GOption X-Git-Tag: GLIB_2_5_5~21 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a0e217e94a030cc6cfeeb879f3391bd2a3e8a499;p=platform%2Fupstream%2Fglib.git Document GOption --- diff --git a/ChangeLog b/ChangeLog index 7981ec335..d191bb727 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/goption.c: Add documentation. + 2004-10-28 Matthias Clasen * glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN, diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 7981ec335..d191bb727 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/goption.c: Add documentation. + 2004-10-28 Matthias Clasen * glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN, diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 7981ec335..d191bb727 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/goption.c: Add documentation. + 2004-10-28 Matthias Clasen * glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN, diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 7981ec335..d191bb727 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/goption.c: Add documentation. + 2004-10-28 Matthias Clasen * glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN, diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 7981ec335..d191bb727 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/goption.c: Add documentation. + 2004-10-28 Matthias Clasen * glib/gmessages.h: Mark g_assert_warning as G_GNUC_NORETURN, diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 4c590cacd..4a0b3c68b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2004-10-29 Matthias Clasen + + * glib/tmpl/option.sgml: Add docs. + 2004-10-28 Matthias Clasen * glib/tmpl/keyfile.sgml: Add some introductory notes. diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml index bd9d15a9e..ed43fdf7b 100644 --- a/docs/reference/glib/tmpl/option.sgml +++ b/docs/reference/glib/tmpl/option.sgml @@ -2,70 +2,128 @@ 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: - - +test -x 1 --long-y foo --flag --long-z=baz -uvw -- 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. + + + An argument consisting solely of two dashes turns off further parsing, any remaining + arguments 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. -@G_OPTION_ERROR_UNKNOWN_OPTION: -@G_OPTION_ERROR_BAD_VALUE: -@G_OPTION_ERROR_FAILED: + +Usage: + testtreemodel [OPTION...] + +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 + - +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. + + + - + - +Error codes returned by option parsing. -@G_OPTION_FLAG_HIDDEN: -@G_OPTION_FLAG_IN_MAIN: +@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. -@G_OPTION_ARG_NONE: -@G_OPTION_ARG_STRING: -@G_OPTION_ARG_INT: -@G_OPTION_ARG_CALLBACK: -@G_OPTION_ARG_FILENAME: -@G_OPTION_ARG_STRING_ARRAY: -@G_OPTION_ARG_FILENAME_ARRAY: + - +The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK +options. -@option_name: -@value: -@data: -@error: -@Returns: +@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 - +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. @@ -134,18 +192,87 @@ Commandline option parser @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. -@long_name: -@short_name: -@flags: -@arg: -@arg_data: -@description: -@arg_description: +@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. + + + +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. +@short_name: If an option has a short name, it can be specified + -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 + 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** + + +@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(). @@ -159,7 +286,14 @@ Commandline option parser - +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. @@ -222,14 +356,18 @@ Commandline option parser - +The type of function that can be called before and after parsing. +@context The active #GOptionContext + @context: -@group: -@data: -@error: -@Returns: +@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 @@ -244,13 +382,17 @@ Commandline option parser - +The type of function to be used as callback when a parse error +occurs. +@context The active #GOptionContext + @context: -@group: -@data: -@error: +@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 @@ -264,12 +406,15 @@ Commandline option parser - +The type of functions which are used to translate user-visible +strings, for output. -@str: -@data: -@Returns: +@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. diff --git a/glib/goption.c b/glib/goption.c index 9efb3185f..7210a2cad 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -112,6 +112,18 @@ g_option_error_quark (void) return q; } +/** + * g_option_context_new: + * @parameter_string: the parameter string to be used in + * output. + * + * Creates a new option context. + * + * Returns: a newly created #GOptionContext, which must be + * freed with g_option_context_free() after use. + * + * Since: 2.6 + */ GOptionContext * g_option_context_new (const gchar *parameter_string) @@ -122,14 +134,22 @@ g_option_context_new (const gchar *parameter_string) context->parameter_string = g_strdup (parameter_string); context->help_enabled = TRUE; + context->ignore_unknown = FALSE; return context; } -void -g_option_context_free (GOptionContext *context) -{ - g_return_if_fail (context != NULL); +/** + * g_option_context_free: + * @context: a #GOptionContext + * + * Frees context and all the groups which have been + * added to it. + * + * Since: 2.6 + */ +void g_option_context_free (GOptionContext *context) { +g_return_if_fail (context != NULL); g_list_foreach (context->groups, (GFunc)g_option_group_free, NULL); g_list_free (context->groups); @@ -145,9 +165,22 @@ g_option_context_free (GOptionContext *context) g_free (context); } -void -g_option_context_set_help_enabled (GOptionContext *context, - gboolean help_enabled) + +/** + * g_option_context_set_help_enabled: + * @context: a #GOptionContext + * @help_enabled: %TRUE to enable , %FALSE to disable it + * + * Enables or disables automatic generation of + * output. By default, g_option_context_parse() recognizes + * , , + * and groupname and creates + * suitable output to stdout. + * + * Since: 2.6 + */ +void g_option_context_set_help_enabled (GOptionContext *context, + gboolean help_enabled) { g_return_if_fail (context != NULL); @@ -155,14 +188,40 @@ g_option_context_set_help_enabled (GOptionContext *context, context->help_enabled = help_enabled; } -gboolean -g_option_context_get_help_enabled (GOptionContext *context) +/** + * g_option_context_get_help_enabled: + * @context: a #GOptionContext + * + * Returns whether automatic generation + * is turned on for @context. See g_option_context_set_help_enabled(). + * + * Returns: %TRUE if automatic help generation is turned on. + * + * Since: 2.6 + */ +gboolean +g_option_context_get_help_enabled (GOptionContext *context) { g_return_val_if_fail (context != NULL, FALSE); - + return context->help_enabled; } +/** + * g_option_context_set_ignore_unknown_options: + * @context: a #GOptionContext + * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce + * an error when unknown options are met + * + * Sets whether to ignore unknown options or not. If an argument is + * ignored, it is left in the @argv array after parsing. By default, + * 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). + * + * Since: 2.6 + **/ void g_option_context_set_ignore_unknown_options (GOptionContext *context, gboolean ignore_unknown) @@ -172,6 +231,17 @@ g_option_context_set_ignore_unknown_options (GOptionContext *context, context->ignore_unknown = ignore_unknown; } +/** + * g_option_context_get_ignore_unknown_options: + * @context: a #GOptionContext + * + * Returns whether unknown options are ignored or not. See + * g_option_context_set_ignore_unknown_options(). + * + * Returns: %TRUE if unknown options are ignored. + * + * Since: 2.6 + **/ gboolean g_option_context_get_ignore_unknown_options (GOptionContext *context) { @@ -180,6 +250,19 @@ g_option_context_get_ignore_unknown_options (GOptionContext *context) return context->ignore_unknown; } +/** + * g_option_context_add_group: + * @context: a #GOptionContext + * @group: the group to add + * + * Adds a #GOptionGroup to the @context, so that parsing with @context + * will recognize the options in the group. Note that the group will + * be freed together with the context when g_option_context_free() is + * called, so you must not free the group yourself after adding it + * to a context. + * + * Since: 2.6 + **/ void g_option_context_add_group (GOptionContext *context, GOptionGroup *group) @@ -193,6 +276,18 @@ g_option_context_add_group (GOptionContext *context, context->groups = g_list_prepend (context->groups, group); } +/** + * g_option_context_set_main_group: + * @context: a #GOptionContext + * @group: the group to set as main group + * + * Sets a #GOptionGroup as main group of the @context. + * This has the same effect as calling g_option_context_add_group(), + * the only difference is that the options in the main group are + * treated differently when generating output. + * + * Since: 2.6 + **/ void g_option_context_set_main_group (GOptionContext *context, GOptionGroup *group) @@ -203,6 +298,18 @@ g_option_context_set_main_group (GOptionContext *context, context->main_group = group; } +/** + * g_option_context_get_main_group: + * @context: a #GOptionContext + * + * Returns a pointer to the main group of @context. + * + * Return value: the main group of @context, or %NULL if @context doesn't + * have a main group. Note that group belongs to @context and should + * not be modified or freed. + * + * Since: 2.6 + **/ GOptionGroup * g_option_context_get_main_group (GOptionContext *context) { @@ -211,6 +318,19 @@ g_option_context_get_main_group (GOptionContext *context) return context->main_group; } +/** + * g_option_context_add_main_entries: + * @context: a #GOptionContext + * @entries: a %NULL-terminated array of #GOptionEntrys + * @translation_domain: a translation domain to use for translating + * the output for the options in @entries + * with gettext(), or %NULL + * + * A convenience function which creates a main group if it doesn't + * exist, adds the @entries to it and sets the translation domain. + * + * Since: 2.6 + **/ void g_option_context_add_main_entries (GOptionContext *context, const GOptionEntry *entries, @@ -814,6 +934,28 @@ free_pending_nulls (GOptionContext *context, context->pending_nulls = NULL; } +/** + * g_option_context_parse: + * @context: a #GOptionContext + * @argc: a pointer to the number of command line arguments. + * @argv: a pointer to the array of command line arguments. + * @error: a return location for errors + * + * Parses the command line arguments, recognizing options + * which have been added to @context. A side-effect of + * calling this function is that g_set_prgname() will be + * called. + * + * If the parsing is successful, any parsed arguments are + * removed from the array and @argc and @argv are updated + * accordingly. In case of an error, @argc and @argv are + * left unmodified. + * + * Return value: %TRUE if the parsing was successful, + * %FALSE if an error occurred + * + * Since: 2.6 + **/ gboolean g_option_context_parse (GOptionContext *context, gint *argc, @@ -1095,7 +1237,27 @@ g_option_context_parse (GOptionContext *context, return FALSE; } - +/** + * g_option_group_new: + * @name: the name for the option group, this is used to provide + * help for the options in this group with @name + * @description: a description for this group to be shown in + * . This string is translated using the translation + * domain or translation function of the group + * @help_description: a description for the @name option. + * This string is translated using the translation domain or translation function + * of the group + * @user_data: user data that will be passed to the pre- and post-parse hooks, + * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL + * @destroy: a function that will be called to free @user_data, or %NULL + * + * Creates a new #GOptionGroup. + * + * Return value: a newly created option group. It should be added + * to a #GOptionContext or freed with g_option_group_free(). + * + * Since: 2.6 + **/ GOptionGroup * g_option_group_new (const gchar *name, const gchar *description, @@ -1116,6 +1278,15 @@ g_option_group_new (const gchar *name, return group; } +/** + * g_option_group_free: + * @group: a #GOptionGroup + * + * Frees a #GOptionGroup. Note that you must not + * free groups which have been added to a #GOptionContext. + * + * Since: 2.6 + **/ void g_option_group_free (GOptionGroup *group) { @@ -1137,6 +1308,15 @@ g_option_group_free (GOptionGroup *group) } +/** + * g_option_group_add_entries: + * @group: a #GOptionGroup + * @entries: a %NULL-terminated array of #GOptionEntrys + * + * Adds the options specified in @entries to @group. + * + * Since: 2.6 + **/ void g_option_group_add_entries (GOptionGroup *group, const GOptionEntry *entries) @@ -1154,6 +1334,22 @@ g_option_group_add_entries (GOptionGroup *group, group->n_entries += n_entries; } +/** + * g_option_group_set_parse_hooks: + * @group: a #GOptionGroup + * @pre_parse_func: a function to call before parsing, or %NULL + * @post_parse_func: a function to call after parsing, or %NULL + * + * Associates two functions with @group which will be called + * from g_option_context_parse() before the first option is parsed + * and after the last option has been parsed, respectively. + * + * Note that the user data to be passed to @pre_parse_func and + * @post_parse_func can be specified when constructing the group + * with g_option_group_new(). + * + * Since: 2.6 + **/ void g_option_group_set_parse_hooks (GOptionGroup *group, GOptionParseFunc pre_parse_func, @@ -1165,6 +1361,20 @@ g_option_group_set_parse_hooks (GOptionGroup *group, group->post_parse_func = post_parse_func; } +/** + * g_option_group_set_error_hook: + * @group: a #GOptionGroup + * @error_func: a function to call when an error occurs + * + * Associates a function with @group which will be called + * from g_option_context_parse() when an error occurs. + * + * Note that the user data to be passed to @pre_parse_func and + * @post_parse_func can be specified when constructing the group + * with g_option_group_new(). + * + * Since: 2.6 + **/ void g_option_group_set_error_hook (GOptionGroup *group, GOptionErrorFunc error_func) @@ -1175,11 +1385,28 @@ g_option_group_set_error_hook (GOptionGroup *group, } +/** + * g_option_group_set_translate_func: + * @group: a #GOptionGroup + * @func: the #GTranslateFunc, or %NULL + * @data: user data to pass to @func, or %NULL + * @destroy_notify: a function which gets called to free @data, or %NULL + * + * Sets the function which is used to translate user-visible + * strings, for output. Different + * groups can use different #GTranslateFuncs. If @func + * is %NULL, strings are not translated. + * + * If you are using gettext(), you only need to set the translation + * domain, see g_option_group_set_translation_domain(). + * + * Since: 2.6 + **/ void g_option_group_set_translate_func (GOptionGroup *group, GTranslateFunc func, gpointer data, - GDestroyNotify notify) + GDestroyNotify destroy_notify) { g_return_if_fail (group != NULL); @@ -1198,6 +1425,16 @@ dgettext_swapped (const gchar *msgid, return dgettext (domainname, msgid); } +/** + * g_option_group_set_translation_domain: + * @group: a #GOptionGroup + * @domain: the domain to use + * + * A convenience function to use gettext() for translating + * user-visible strings. + * + * Since: 2.6 + **/ void g_option_group_set_translation_domain (GOptionGroup *group, const gchar *domain)