Support for a program description in help

Closes davetron5000#40

bin/gli

@@ -19,6 +19,8 @@ require 'gli_version'
 
 include GLI
 
+program_desc 'gli allows you to create the scaffolding for a GLI-powered application'
+
 version GLI::VERSION
 desc 'Be verbose'
 switch :v

gli.rdoc

@@ -1,5 +1,6 @@
 = <tt>gli</tt>
 
+gli allows you to create the scaffolding for a GLI-powered application
     gli [global options] command_name [command-specific options] [--] arguments...
 
 * Use the command +help+ to get a summary of commands

lib/gli.rb

@@ -24,6 +24,7 @@ module GLI
   @@use_openstruct = false
   @@version = nil
   @@stderr = $stderr
+  @@program_desc = nil
 
   # Override the device of stderr; exposed only for testing
   def error_device=(e) #:nodoc:
@@ -38,6 +39,7 @@ def reset # :nodoc:
     @@version = nil
     @@config_file = nil
     @@use_openstruct = false
+    @@prog_desc = nil
     clear_nexts
   end
 
@@ -47,6 +49,17 @@ def reset # :nodoc:
   # +description+:: A String of the short descripiton of the switch, flag, or command following
   def desc(description); @@next_desc = description; end
 
+  # Describe the overall application/programm.  This should be a one-sentence summary
+  # of what your program does that will appear in the help output.
+  #
+  # +description+:: A String of the short description of your program's purpose
+  def program_desc(description=nil) 
+    if description
+      @@program_desc = description
+    end
+    @@program_desc
+  end
+
   # Provide a longer, more detailed description.  This
   # will be reformatted and wrapped to fit in the terminal's columns
   #

lib/support/help.rb

@@ -47,6 +47,10 @@ def execute(global_options,options,arguments)
     private
 
     def list_global_flags
+      if GLI.program_desc
+        @@output.puts wrap(GLI.program_desc,0)
+        @@output.puts
+      end
       usage = "usage: #{GLI.program_name} "
       all_options = GLI.switches.merge(GLI.flags)
       if !all_options.empty?

lib/support/rdoc.rb

@@ -48,6 +48,10 @@ def create_manpage
     def create_rdoc
       File.open("#{GLI.program_name}.rdoc",'w') do |file|
         file << "= <tt>#{GLI.program_name}</tt>\n\n"
+        if GLI.program_desc
+          file << GLI.program_desc
+          file << "\n\n"
+        end
         file << "    "
         file << GLI.program_name
         file << " "

test/tc_command.rb

@@ -23,6 +23,7 @@ def to_s
 
   def setup
     GLI.reset
+    GLI.program_desc 'A super awesome program'
     GLI.desc 'Some Global Option'
     GLI.switch :g
     GLI.switch :blah
@@ -154,7 +155,7 @@ def test_unknown_argument
   def test_help
     args = %w(help)
     GLI.run(args)
-    ['\[global options\]','\[command options\]','Global Options:'].each do |opt|
+    ['\[global options\]','\[command options\]','Global Options:','A super awesome program'].each do |opt|
       assert_contained(@fake_stdout,/#{opt}/)
     end
   end