[Ada] in GNAT.Command_Line, allow user to replace the standard help message

[Arnaud Charlet]

GNAT.Command_Line automatically computes a help message showing all supported
switches. This patch allows to replace this automatic message by a user given
one, in case the automatic one does not fit.

Tested on x86_64-pc-linux-gnu, committed on trunk

2011-09-05  Johannes Kanig  <ka...@adacore.com>

        * g-comlin.adb (Set_Usage): Additional optional argument to set help
        message.
        (Display_Help): display the user given help message, if available.


Index: g-comlin.adb
===================================================================
--- g-comlin.adb        (revision 178536)
+++ g-comlin.adb        (working copy)
@@ -3026,9 +3026,10 @@
    ---------------
 
    procedure Set_Usage
-     (Config : in out Command_Line_Configuration;
-      Usage  : String := "[switches] [arguments]";
-      Help   : String := "")
+     (Config   : in out Command_Line_Configuration;
+      Usage    : String := "[switches] [arguments]";
+      Help     : String := "";
+      Help_Msg : String := "")
    is
    begin
       if Config = null then
@@ -3036,8 +3037,9 @@
       end if;
 
       Free (Config.Usage);
-      Config.Usage := new String'(Usage);
-      Config.Help  := new String'(Help);
+      Config.Usage    := new String'(Usage);
+      Config.Help     := new String'(Help);
+      Config.Help_Msg := new String'(Help_Msg);
    end Set_Usage;
 
    ------------------
@@ -3222,12 +3224,15 @@
                    & " [switches] [arguments]");
       end if;
 
-      Display_Section_Help ("");
-
-      if Config.Sections /= null and then Config.Switches /= null then
-         for S in Config.Sections'Range loop
-            Display_Section_Help (Config.Sections (S).all);
-         end loop;
+      if Config.Help_Msg /= null and then Config.Help_Msg.all /= "" then
+         Put_Line (Config.Help_Msg.all);
+      else
+         Display_Section_Help ("");
+         if Config.Sections /= null and then Config.Switches /= null then
+            for S in Config.Sections'Range loop
+               Display_Section_Help (Config.Sections (S).all);
+            end loop;
+         end if;
       end if;
    end Display_Help;
 
Index: g-comlin.ads
===================================================================
--- g-comlin.ads        (revision 178438)
+++ g-comlin.ads        (working copy)
@@ -664,11 +664,14 @@
    --  Output is always initialized to the empty string.
 
    procedure Set_Usage
-     (Config : in out Command_Line_Configuration;
-      Usage  : String := "[switches] [arguments]";
-      Help   : String := "");
+     (Config   : in out Command_Line_Configuration;
+      Usage    : String := "[switches] [arguments]";
+      Help     : String := "";
+      Help_Msg : String := "");
    --  Defines the general format of the call to the application, and a short
-   --  help text. These are both displayed by Display_Help
+   --  help text. These are both displayed by Display_Help. When a non-empty
+   --  Help_Msg is given, it is used by Display_Help instead of the
+   --  automatically generated list of supported switches.
 
    procedure Display_Help (Config : Command_Line_Configuration);
    --  Display the help for the tool (ie its usage, and its supported switches)
@@ -1134,6 +1137,7 @@
       Aliases  : Alias_Definitions_List;
       Usage    : GNAT.OS_Lib.String_Access;
       Help     : GNAT.OS_Lib.String_Access;
+      Help_Msg : GNAT.OS_Lib.String_Access;
       Switches : Switch_Definitions_List;
       --  List of expected switches (Used when expanding switch groups)
    end record;