From a052fd1202a4375e52f30215d8fde994b852324d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 13 May 2006 04:23:38 +0000 Subject: [PATCH] Allow optional summary and description texts before and after the option 2006-05-13 Matthias Clasen * glib/glib.symbols: * glib/goption.h: * glib/goption.c: Allow optional summary and description texts before and after the option descriptions, and add a way to translate them. (#336120, Behdad Esfahbod) --- ChangeLog | 8 + ChangeLog.pre-2-12 | 8 + docs/reference/ChangeLog | 4 + docs/reference/glib/glib-sections.txt | 8 +- glib/glib.symbols | 6 + glib/goption.c | 232 ++++++++++++++++++++++---- glib/goption.h | 16 +- 7 files changed, 247 insertions(+), 35 deletions(-) diff --git a/ChangeLog b/ChangeLog index 68643763b..6c6d5c2af 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2006-05-13 Matthias Clasen + + * glib/glib.symbols: + * glib/goption.h: + * glib/goption.c: Allow optional summary and description + texts before and after the option descriptions, and add + a way to translate them. (#336120, Behdad Esfahbod) + 2006-05-12 Tor Lillqvist * glib/giowin32.c (g_io_win32_sock_set_flags): Implement diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 68643763b..6c6d5c2af 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,11 @@ +2006-05-13 Matthias Clasen + + * glib/glib.symbols: + * glib/goption.h: + * glib/goption.c: Allow optional summary and description + texts before and after the option descriptions, and add + a way to translate them. (#336120, Behdad Esfahbod) + 2006-05-12 Tor Lillqvist * glib/giowin32.c (g_io_win32_sock_set_flags): Implement diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 010a24dfc..ffacc7c1d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2006-05-13 Matthias Clasen + + * glib/glib-sections.txt: Document new api. + 2006-05-11 Bastien Nocera * glib/tmpl/option.sgml: add documentation for G_OPTION_ARG_INT64 diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 29bb7e68b..687847b34 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -954,6 +954,13 @@ G_OPTION_ERROR GOptionArgFunc GOptionContext g_option_context_new +g_option_context_set_summary +g_option_context_get_summary +g_option_context_set_description +g_option_context_get_description +GTranslateFunc +g_option_context_set_translate_func +g_option_context_set_translation_domain g_option_context_free g_option_context_parse g_option_context_set_help_enabled @@ -976,7 +983,6 @@ GOptionParseFunc g_option_group_set_parse_hooks GOptionErrorFunc g_option_group_set_error_hook -GTranslateFunc g_option_group_set_translate_func g_option_group_set_translation_domain diff --git a/glib/glib.symbols b/glib/glib.symbols index 05aac3bd4..61f33e45d 100644 --- a/glib/glib.symbols +++ b/glib/glib.symbols @@ -745,14 +745,20 @@ g_option_context_add_group g_option_context_add_main_entries g_option_error_quark g_option_context_free +g_option_context_get_description g_option_context_get_help_enabled g_option_context_get_ignore_unknown_options g_option_context_get_main_group +g_option_context_get_summary g_option_context_new g_option_context_parse +g_option_context_set_description g_option_context_set_help_enabled g_option_context_set_ignore_unknown_options g_option_context_set_main_group +g_option_context_set_summary +g_option_context_set_translate_func +g_option_context_set_translation_domain g_option_group_add_entries g_option_group_free g_option_group_new diff --git a/glib/goption.c b/glib/goption.c index 10d22b3da..56fdb3a17 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -72,39 +72,45 @@ typedef struct struct _GOptionContext { - GList *groups; + GList *groups; - gchar *parameter_string; + gchar *parameter_string; + gchar *summary; + gchar *description; - gboolean help_enabled; - gboolean ignore_unknown; + GTranslateFunc translate_func; + GDestroyNotify translate_notify; + gpointer translate_data; + + guint help_enabled : 1; + guint ignore_unknown : 1; - GOptionGroup *main_group; + GOptionGroup *main_group; /* We keep a list of change so we can revert them */ - GList *changes; + GList *changes; - /* We also keep track of all argv elements that should be NULLed or - * modified. + /* We also keep track of all argv elements + * that should be NULLed or modified. */ - GList *pending_nulls; + GList *pending_nulls; }; struct _GOptionGroup { - gchar *name; - gchar *description; - gchar *help_description; + gchar *name; + gchar *description; + gchar *help_description; - GDestroyNotify destroy_notify; - gpointer user_data; + GDestroyNotify destroy_notify; + gpointer user_data; - GTranslateFunc translate_func; - GDestroyNotify translate_notify; - gpointer translate_data; + GTranslateFunc translate_func; + GDestroyNotify translate_notify; + gpointer translate_data; - GOptionEntry *entries; - gint n_entries; + GOptionEntry *entries; + gint n_entries; GOptionParseFunc pre_parse_func; GOptionParseFunc post_parse_func; @@ -131,20 +137,22 @@ g_option_error_quark (void) * * Creates a new option context. * - * The @parameter_text can serve multiple purposes. It can be used + * The @parameter_string can serve multiple purposes. It can be used * to add descriptions for "rest" arguments, which are not parsed by * the #GOptionContext, typically something like "FILES" or - * "FILE1 FILE2...". (If you are using #G_OPTION_REMAINING for + * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for * collecting "rest" arguments, GLib handles this automatically by * using the @arg_description of the corresponding #GOptionEntry in - * the usage summary.) + * the usage summary. * - * Another common usage is to give a summary of the program - * functionality. This can be a short summary on the same line, - * like " - frob the strings", or a longer description in a paragraph - * below the usage summary. In this case, @parameter_string should start - * with two newlines, to separate the description from the usage summary: - * "\n\nA program to frob strings, which will..." + * Another usage is to give a short summary of the program + * functionality, like " - frob the strings", which will be displayed + * in the same line as the usage. For a longer description of the + * program functionality that should be displayed as a paragraph + * below the usage line, use g_option_context_set_summary(). + * + * Note that the @parameter_string is translated (see + * g_option_context_set_translate_func()). * * Returns: a newly created #GOptionContext, which must be * freed with g_option_context_free() after use. @@ -189,7 +197,12 @@ void g_option_context_free (GOptionContext *context) free_pending_nulls (context, FALSE); g_free (context->parameter_string); + g_free (context->summary); + g_free (context->description); + if (context->translate_notify) + (* context->translate_notify) (context->translate_data); + g_free (context); } @@ -466,23 +479,27 @@ print_help (GOptionContext *context, rest_description = NULL; if (context->main_group) { + for (i = 0; i < context->main_group->n_entries; i++) { entry = &context->main_group->entries[i]; if (entry->long_name[0] == 0) { - rest_description = entry->arg_description; + rest_description = TRANSLATE (context->main_group, entry->arg_description); break; } } } - + g_print ("%s\n %s %s%s%s%s%s\n\n", _("Usage:"), g_get_prgname(), _("[OPTION...]"), rest_description ? " " : "", rest_description ? rest_description : "", context->parameter_string ? " " : "", - context->parameter_string ? context->parameter_string : ""); + context->parameter_string ? TRANSLATE (context, context->parameter_string) : ""); + + if (context->summary) + g_print ("%s\n\n", TRANSLATE (context, context->summary)); memset (seen, 0, sizeof (gboolean) * 256); shadow_map = g_hash_table_new (g_str_hash, g_str_equal); @@ -643,7 +660,10 @@ print_help (GOptionContext *context, g_print ("\n"); } - + + if (context->description) + g_print ("%s\n", TRANSLATE (context, context->description)); + exit (0); } @@ -1894,5 +1914,153 @@ g_option_group_set_translation_domain (GOptionGroup *group, g_free); } +/** + * g_option_context_set_translate_func: + * @context: a #GOptionContext + * @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 the contexts + * user-visible strings, for output. + * If @func is %NULL, strings are not translated. + * + * Note that option groups have their own translation functions, + * this function only affects the @parameter_string (see g_option_context_nex()), + * the summary (see g_option_context_set_summary()) and the description + * (see g_option_context_set_description()). + * + * If you are using gettext(), you only need to set the translation + * domain, see g_context_group_set_translation_domain(). + * + * Since: 2.12 + **/ +void +g_option_context_set_translate_func (GOptionContext *context, + GTranslateFunc func, + gpointer data, + GDestroyNotify destroy_notify) +{ + g_return_if_fail (context != NULL); + + if (context->translate_notify) + context->translate_notify (context->translate_data); + + context->translate_func = func; + context->translate_data = data; + context->translate_notify = destroy_notify; +} + +/** + * g_option_context_set_translation_domain: + * @context: a #GOptionContext + * @domain: the domain to use + * + * A convenience function to use gettext() for translating + * user-visible strings. + * + * Since: 2.12 + **/ +void +g_option_context_set_translation_domain (GOptionContext *context, + const gchar *domain) +{ + g_return_if_fail (context != NULL); + + g_option_context_set_translate_func (context, + (GTranslateFunc)dgettext_swapped, + g_strdup (domain), + g_free); +} + +/** + * g_option_context_set_summary: + * @context: a #GOptionContext + * @summary: a string to be shown in output + * before the list of options, or %NULL + * + * Adds a string to be displayed in output + * before the list of options. This is typically a summary of the + * program functionality. + * + * Note that the summary is translated (see + * g_option_context_set_translate_func()). + * + * Since: 2.12 + */ +void +g_option_context_set_summary (GOptionContext *context, + const gchar *summary) +{ + g_return_if_fail (context != NULL); + + g_free (context->summary); + context->summary = g_strdup (summary); +} + + +/** + * g_option_context_get_summary: + * @context: a #GOptionContext + * + * Returns the summary. See g_option_context_set_summary(). + * + * Returns: the summary + * + * Since: 2.12 + */ +G_CONST_RETURN gchar * +g_option_context_get_summary (GOptionContext *context) +{ + g_return_val_if_fail (context != NULL, NULL); + + return context->summary; +} + +/** + * g_option_context_set_description: + * @context: a #GOptionContext + * @description: a string to be shown in output + * after the list of options, or %NULL + * + * Adds a string to be displayed in output + * after the list of options. This text often includes a bug reporting + * address. + * + * Note that the summary is translated (see + * g_option_context_set_translate_func()). + * + * Since: 2.12 + */ +void +g_option_context_set_description (GOptionContext *context, + const gchar *description) +{ + g_return_if_fail (context != NULL); + + g_free (context->description); + context->description = g_strdup (description); +} + + +/** + * g_option_context_get_description: + * @context: a #GOptionContext + * + * Returns the description. See g_option_context_set_description(). + * + * Returns: the description + * + * Since: 2.12 + */ +G_CONST_RETURN gchar * +g_option_context_get_description (GOptionContext *context) +{ + g_return_val_if_fail (context != NULL, NULL); + + return context->description; +} + + #define __G_OPTION_C__ #include "galiasdef.c" diff --git a/glib/goption.h b/glib/goption.h index 478ed0d4c..8f8ecc83a 100644 --- a/glib/goption.h +++ b/glib/goption.h @@ -97,6 +97,12 @@ struct _GOptionEntry #define G_OPTION_REMAINING "" GOptionContext *g_option_context_new (const gchar *parameter_string); +void g_option_context_set_summary (GOptionContext *context, + const gchar *summary); +G_CONST_RETURN gchar *g_option_context_get_summary (GOptionContext *context); +void g_option_context_set_description (GOptionContext *context, + const gchar *description); +G_CONST_RETURN gchar *g_option_context_get_description (GOptionContext *context); void g_option_context_free (GOptionContext *context); void g_option_context_set_help_enabled (GOptionContext *context, gboolean help_enabled); @@ -112,9 +118,15 @@ gboolean g_option_context_parse (GOptionContext *context, gint *argc, gchar ***argv, GError **error); +void g_option_context_set_translate_func (GOptionContext *context, + GTranslateFunc func, + gpointer data, + GDestroyNotify destroy_notify); +void g_option_context_set_translation_domain (GOptionContext *context, + const gchar *domain); -void g_option_context_add_group (GOptionContext *context, - GOptionGroup *group); +void g_option_context_add_group (GOptionContext *context, + GOptionGroup *group); void g_option_context_set_main_group (GOptionContext *context, GOptionGroup *group); GOptionGroup *g_option_context_get_main_group (GOptionContext *context);