From 59785123580f92c4a49bb6a4f2c4efe33c084afb Mon Sep 17 00:00:00 2001
From: BJ Dierkes <wdierkes@rackspace.com>
Date: Mon, 20 Aug 2012 21:18:22 -0500
Subject: [PATCH] Resolved Issue #161 - Ability to override `usage`

---
 cement/core/controller.py      | 12 ++++++++++++
 tests/core/controller_tests.py | 11 ++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/cement/core/controller.py b/cement/core/controller.py
index 62654826..7feb6651 100644
--- a/cement/core/controller.py
+++ b/cement/core/controller.py
@@ -23,6 +23,7 @@ def controller_validator(klass, obj):
         'config_section',
         'config_defaults',
         'arguments',
+        'usage',
         'epilog',
         'stacked_on',
         'hide',
@@ -243,6 +244,14 @@ class CementBaseController(handler.CementBaseHandler):
         The text that is displayed at the bottom when '--help' is passed.
         """
         
+        usage = None
+        """
+        The text that is displayed at the top when '--help' is passed.  
+        Although the default is `None`, Cement will set this to a generic
+        usage based on the `prog`, `controller` name, etc if nothing else is
+        passed.
+        """
+        
         argument_formatter = argparse.RawDescriptionHelpFormatter
         """
         The argument formatter class to use to display --help output.
@@ -532,6 +541,9 @@ class CementBaseController(handler.CementBaseHandler):
     def _usage_text(self):
         """Returns the usage text displayed when '--help' is passed."""
         
+        if self._meta.usage is not None:
+            return self._meta.usage
+            
         if self == self.app._meta.base_controller:
             txt = "%s <CMD> -opt1 --opt2=VAL [arg1] [arg2] ..." % \
                 self.app.args.prog
diff --git a/tests/core/controller_tests.py b/tests/core/controller_tests.py
index b0914af5..59414335 100644
--- a/tests/core/controller_tests.py
+++ b/tests/core/controller_tests.py
@@ -64,7 +64,9 @@ class TestBaseController2(controller.CementBaseController):
         config_defaults = {}
         arguments = []
         hide = False
-    
+        epilog = 'Test Epilog'
+        usage = 'Test Usage'
+        
     @controller.expose()
     def my_command(self):
         pass
@@ -381,3 +383,10 @@ class ControllerTestCase(test.CementTestCase):
         except exc.FrameworkError as e:
             self.ok(e.msg.find('collides'))
             raise
+
+    def test_usage_text(self):
+        self.app.setup()
+        contr = TestBaseController2()
+        contr._setup(self.app)
+        self.eq(contr._usage_text, 'Test Usage')
+    
\ No newline at end of file