luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-08 03:45:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

Allow optional summary and description texts before and after the option

Browse Source 
2006-05-13  Matthias Clasen  <mclasen@redhat.com>

	* 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)
This commit is contained in:
Matthias Clasen 2006-05-13 04:23:38 +00:00 committed by Matthias Clasen
parent d5b919142b
commit a052fd1202
7 changed files with 247 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
ChangeLog
View File

@ -1,3 +1,11 @@
2006-05-13 Matthias Clasen <mclasen@redhat.com>
* 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 <tml@novell.com>
* glib/giowin32.c (g_io_win32_sock_set_flags): Implement

8
ChangeLog.pre-2-12
View File

@ -1,3 +1,11 @@
2006-05-13 Matthias Clasen <mclasen@redhat.com>
* 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 <tml@novell.com>
* glib/giowin32.c (g_io_win32_sock_set_flags): Implement

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2006-05-13 Matthias Clasen <mclasen@redhat.com>
* glib/glib-sections.txt: Document new api.
2006-05-11 Bastien Nocera <hadess@hadess.net>
* glib/tmpl/option.sgml: add documentation for G_OPTION_ARG_INT64

8
docs/reference/glib/glib-sections.txt
View File

@ -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
<SUBSECTION Private>

6
glib/glib.symbols
View File

@ -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

198
glib/goption.c
View File

@ -75,17 +75,23 @@ struct _GOptionContext
GList *groups;
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;
/* We keep a list of change so we can revert them */
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;
};
@ -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,6 +197,11 @@ 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,12 +479,13 @@ 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;
}
}
@ -482,7 +496,10 @@ print_help (GOptionContext *context,
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);
@ -644,6 +661,9 @@ 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 <option>--help</option> 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 <option>--help</option> output
* before the list of options, or %NULL
*
* Adds a string to be displayed in <option>--help</option> 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 <option>--help</option> output
* after the list of options, or %NULL
*
* Adds a string to be displayed in <option>--help</option> 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"

12
glib/goption.h
View File

@ -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,6 +118,12 @@ 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);