New function to get the formatted help string. (#336089, Dom Lachowicz)

2007-04-24  Matthias Clasen  <mclasen@redhat.com>

        * glib/glib.symbols:
        * glib/goption.h:
        * glib/goption.c (g_option_context_get_help): New function to
        get the formatted help string.  (#336089, Dom Lachowicz)

svn path=/trunk/; revision=5456

diff --git a/ChangeLog b/ChangeLog
index a5b39c0..59b4c16 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-04-24  Matthias Clasen  <mclasen@redhat.com>
+
+       * glib/glib.symbols:
+       * glib/goption.h:
+       * glib/goption.c (g_option_context_get_help): New function to
+       get the formatted help string.  (#336089, Dom Lachowicz)
+
 2007-04-24  Michael Natterer  <mitch@imendio.com>
 
        * gobject/gparamspecs.c (param_string_validate): don't free or

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index b745125..643fe90 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2007-04-24  Matthias Clasen  <mclasen@redhat.com>
+
+       * glib/glib-sections.txt: Add g_option_context_get_help.
+
 2007-04-11  Emmanuele Bassi  <ebassi@gnome.org>
 
        * glib/glib-sections.txt: Add new hash functions.

diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index ec7eac8..8eb60dc 100644 (file)
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1020,6 +1020,7 @@ g_option_context_set_help_enabled
 g_option_context_get_help_enabled
 g_option_context_set_ignore_unknown_options
 g_option_context_get_ignore_unknown_options
+g_option_context_get_help
 GOptionArg
 GOptionFlags
 G_OPTION_REMAINING

diff --git a/glib/glib.symbols b/glib/glib.symbols
index bc6a307..060e866 100644 (file)
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -769,6 +769,7 @@ 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_context_get_help
 g_option_group_add_entries
 g_option_group_free
 g_option_group_new
@@ -1426,6 +1427,8 @@ g_regex_free
 g_regex_optimize
 g_regex_copy
 g_regex_get_pattern
+g_regex_get_max_backref
+g_regex_get_capture_count
 g_regex_clear
 g_regex_match_simple
 g_regex_match

diff --git a/glib/goption.c b/glib/goption.c
index b0fcab7..3a89191 100644 (file)
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -24,11 +24,13 @@
 #include "goption.h"
 #include "glib.h"
 #include "glibintl.h"
+#include "gprintf.h"
 
 #include "galias.h"
 
 #include <string.h>
 #include <stdlib.h>
+#include <stdio.h>
 #include <errno.h>
 
 #define TRANSLATE(group, str) (((group)->translate_func ? (* (group)->translate_func) ((str), (group)->translate_data) : (str)))
@@ -490,10 +492,11 @@ calculate_max_length (GOptionGroup *group)
 static void
 print_entry (GOptionGroup       *group,
             gint                max_length,
-            const GOptionEntry *entry)
+            const GOptionEntry *entry,
+             GString            *string)
 {
   GString *str;
-
+  
   if (entry->flags & G_OPTION_FLAG_HIDDEN)
     return;
 
@@ -510,16 +513,34 @@ print_entry (GOptionGroup       *group,
   if (entry->arg_description)
     g_string_append_printf (str, "=%s", TRANSLATE (group, entry->arg_description));
   
-  g_print ("%s%*s %s\n", str->str,
-          (int) (max_length + 4 - _g_utf8_strwidth (str->str, -1)), "",
-          entry->description ? TRANSLATE (group, entry->description) : "");
+  g_string_append_printf (string, "%s%*s %s\n", str->str,
+                         (int) (max_length + 4 - _g_utf8_strwidth (str->str, -1)), "",
+                         entry->description ? TRANSLATE (group, entry->description) : "");
   g_string_free (str, TRUE);  
 }
 
-static void
-print_help (GOptionContext *context,
-           gboolean        main_help,
-           GOptionGroup   *group) 
+/**
+ * g_option_context_get_help: 
+ * @context: a #GOptionContext
+ * @main_help: if %TRUE, only include the main group 
+ * @group: the #GOptionGroup to create help for, or %NULL
+ *
+ * Returns a formatted, translated help text for the given context.
+ * To obtain the text produced by <option>--help</option>, call
+ * <literal>g_option_context_get_help (context, TRUE, NULL)</literal>.
+ * To obtain the text produced by <option>--help-all</option>, call
+ * <literal>g_option_context_get_help (context, FALSE, NULL)</literal>.
+ * To obtain the help text for an option group, call
+ * <literal>g_option_context_get_help (context, FALSE, group)</literal>.
+ *
+ * Returns: A newly allocated string containing the help text
+ *
+ * Since: 2.14
+ */
+gchar *
+g_option_context_get_help (GOptionContext *context,
+                          gboolean        main_help,
+                          GOptionGroup   *group)
 {
   GList *list;
   gint max_length, len;
@@ -528,7 +549,10 @@ print_help (GOptionContext *context,
   GHashTable *shadow_map;
   gboolean seen[256];
   const gchar *rest_description;
-  
+  GString *string;
+
+  string = g_string_sized_new (1024);
+
   rest_description = NULL;
   if (context->main_group)
     {
@@ -544,15 +568,28 @@ print_help (GOptionContext *context,
        }
     }
 
-  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 ? TRANSLATE (context, context->parameter_string) : "");
+  g_string_append_printf (string, "%s\n  %s %s", 
+                         _("Usage:"), g_get_prgname(), _("[OPTION...]"));
+
+  if (rest_description)
+    {
+      g_string_printf (string, " ");
+      g_string_printf (string, rest_description);
+    }
+
+  if (context->parameter_string)
+    {
+      g_string_printf (string, " ");
+      g_string_printf (string, TRANSLATE (context, context->parameter_string));
+    }
+
+  g_string_append (string, "\n\n");
 
   if (context->summary)
-    g_print ("%s\n\n", TRANSLATE (context, context->summary));
+    {
+      g_string_append (string, TRANSLATE (context, context->summary));
+      g_string_append (string, "\n\n");
+    }
 
   memset (seen, 0, sizeof (gboolean) * 256);
   shadow_map = g_hash_table_new (g_str_hash, g_str_equal);
@@ -635,36 +672,39 @@ print_help (GOptionContext *context,
     {
       list = context->groups;
       
-      g_print ("%s\n  -%c, --%-*s %s\n", 
-              _("Help Options:"), '?', max_length - 4, "help", 
-              _("Show help options"));
+      g_string_append_printf (string, "%s\n  -%c, --%-*s %s\n", 
+                             _("Help Options:"), '?', max_length - 4, "help", 
+                             _("Show help options"));
       
       /* We only want --help-all when there are groups */
       if (list)
-       g_print ("  --%-*s %s\n", max_length, "help-all", 
-                _("Show all help options"));
+       g_string_append_printf (string, "  --%-*s %s\n", 
+                                max_length, "help-all", 
+                                _("Show all help options"));
       
       while (list)
        {
          GOptionGroup *group = list->data;
          
-         g_print ("  --help-%-*s %s\n", max_length - 5, group->name, 
-                  TRANSLATE (group, group->help_description));
+         g_string_append_printf (string, "  --help-%-*s %s\n", 
+                                  max_length - 5, group->name, 
+                                 TRANSLATE (group, group->help_description));
          
          list = list->next;
        }
 
-      g_print ("\n");
+      g_string_append (string, "\n");
     }
 
   if (group)
     {
       /* Print a certain group */
       
-      g_print ("%s\n", TRANSLATE (group, group->description));
+      g_string_append (string, TRANSLATE (group, group->description));
+      g_string_append (string, "\n");
       for (i = 0; i < group->n_entries; i++)
-       print_entry (group, max_length, &group->entries[i]);
-      g_print ("\n");
+       print_entry (group, max_length, &group->entries[i], string);
+      g_string_append (string, "\n");
     }
   else if (!main_help)
     {
@@ -676,13 +716,13 @@ print_help (GOptionContext *context,
        {
          GOptionGroup *group = list->data;
 
-         g_print ("%s\n", group->description);
-
+         g_string_append (string, group->description);
+          g_string_append (string, "\n");
          for (i = 0; i < group->n_entries; i++)
            if (!(group->entries[i].flags & G_OPTION_FLAG_IN_MAIN))
-             print_entry (group, max_length, &group->entries[i]);
+             print_entry (group, max_length, &group->entries[i], string);
          
-         g_print ("\n");
+         g_string_append (string, "\n");
          list = list->next;
        }
     }
@@ -692,12 +732,12 @@ print_help (GOptionContext *context,
     {
       list = context->groups;
 
-      g_print ("%s\n", _("Application Options:"));
-
+      g_string_append (string,  _("Application Options:"));
+      g_string_append (string, "\n");
       if (context->main_group)
        for (i = 0; i < context->main_group->n_entries; i++) 
          print_entry (context->main_group, max_length, 
-                      &context->main_group->entries[i]);
+                      &context->main_group->entries[i], string);
 
       while (list != NULL)
        {
@@ -706,18 +746,35 @@ print_help (GOptionContext *context,
          /* Print main entries from other groups */
          for (i = 0; i < group->n_entries; i++)
            if (group->entries[i].flags & G_OPTION_FLAG_IN_MAIN)
-             print_entry (group, max_length, &group->entries[i]);
+             print_entry (group, max_length, &group->entries[i], string);
          
          list = list->next;
        }
 
-      g_print ("\n");
+      g_string_append (string, "\n");
     }
  
   if (context->description)
-    g_print ("%s\n", TRANSLATE (context, context->description));
- 
-  exit (0);
+    {
+      g_string_append (string, TRANSLATE (context, context->description));
+      g_string_append (string, "\n");
+    }
+
+  return g_string_free (string, FALSE);
+}
+
+static void
+print_help (GOptionContext *context,
+           gboolean        main_help,
+           GOptionGroup   *group)
+{
+  gchar *help;
+
+  help = g_option_context_get_help (context, main_help, group);
+  g_printf (help);
+  g_free (help);
+
+  exit (0);  
 }
 
 static gboolean

diff --git a/glib/goption.h b/glib/goption.h
index 8f8ecc8..908e531 100644 (file)
--- a/glib/goption.h
+++ b/glib/goption.h
@@ -130,7 +130,9 @@ void            g_option_context_add_group      (GOptionContext *context,
 void          g_option_context_set_main_group (GOptionContext *context,
                                               GOptionGroup   *group);
 GOptionGroup *g_option_context_get_main_group (GOptionContext *context);
-
+gchar        *g_option_context_get_help       (GOptionContext *context,
+                                               gboolean        main_help,
+                                               GOptionGroup   *group);
 
 GOptionGroup *g_option_group_new                    (const gchar        *name,
                                                     const gchar        *description,