Make the GenerateHelpText format easily configurable.

git-svn-id: http://scons.tigris.org/svn/scons/trunk@1247 fdb21ef1-2011-0410-befe-b5e4ea1792b1

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index ae57f829d5b7e8c86431d2e4902fe35b444b8081..3aac25c76bba4a4c469f0bfb7125656d50cf115c 100644 (file)
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -7723,6 +7723,18 @@ the Environment() function:
 env = Environment(options=opts)
 .EE
 
+.IP
+The text file(s) that were specified
+when the Options object was created
+are executed as Python scripts,
+and the values of (global) Python variables set in the file
+are added to the construction environment.
+Example:
+
+.ES
+CC = 'my_cc'
+.EE
+
 .TP
 .RI Save( filename ", " env )
 This saves the currently set options into a script file named  
@@ -7766,12 +7778,30 @@ Help(opts.GenerateHelpText(env))
 Help(opts.GenerateHelpText(env, sort=cmp))
 .EE
 
-The text based SConscript file is executed as a Python script, and the
-global variables are queried for customizable construction
-variables. Example:
+.TP
+.RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
+This method returns a formatted string
+containing the printable help text
+for one option.
+It is normally not called directly,
+but is called by the
+.IR GenerateHelpText ()
+method to create the returned help text.
+It may be overridden with your own
+function that takes the arguments specified above
+and returns a string of help text formatted to your liking.
+Note that the
+.IR GenerateHelpText ()
+will not put any blank lines or extra
+characters in between the entries,
+so you must add those characters to the returned
+string if you want the entries separated.
 
 .ES
-CC = 'my_cc'
+def my_format(env, opt, help, default, actual):
+    fmt = "\n%s: default=%s actual=%s (%s)\n"
+    return fmt % (opt, default. actual, help)
+opts.FormatOptionHelpText = my_format
 .EE
 
 To make it more convenient to work with customizable Options,

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 2fa54abf33b0bc34d9b64c4fcda3cadbdb3abb0d..0535e10a5cc893aaed26de460838b6d8f7f45ce2 100644 (file)
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -225,6 +225,9 @@ RELEASE 0.97 - XXX
   - Enhanced the SCons setup.py script to install man pages on
     UNIX/Linux systems.
 
+  - Add support for an Options.FormatOptionHelpText() method that can
+    be overridden to customize the format of Options help text.
+
   From Wayne Lee:
 
   - Avoid "maximum recursion limit" errors when removing $(-$) pairs

diff --git a/src/engine/SCons/Options/OptionsTests.py b/src/engine/SCons/Options/OptionsTests.py
index b99aa985bbdd7d664e0527288a1ee5daa5087662..96f2e2b2c31bf1397e20ed48f4bb4abe269f769e 100644 (file)
--- a/src/engine/SCons/Options/OptionsTests.py
+++ b/src/engine/SCons/Options/OptionsTests.py
@@ -375,6 +375,7 @@ class OptionsTestCase(unittest.TestCase):
                                 'THIS_SHOULD_WORK' : 'baz' })
 
     def test_GenerateHelpText(self):
+        """Test generating the default format help text"""
         opts = SCons.Options.Options()
 
         opts.Add('ANSWER',
@@ -430,6 +431,56 @@ B: b - alpha test
 """
         text = opts.GenerateHelpText(env, sort=cmp)
         assert text == expectAlpha, text
+
+    def test_FormatOptionHelpText(self):
+        """Test generating custom format help text"""
+        opts = SCons.Options.Options()
+
+        def my_format(env, opt, help, default, actual):
+            return '%s %s %s %s\n' % (opt, default, actual, help)
+
+        opts.FormatOptionHelpText = my_format
+
+        opts.Add('ANSWER',
+                 'THE answer to THE question',
+                 "42",
+                 check,
+                 lambda x: int(x) + 12)
+
+        opts.Add('B',
+                 'b - alpha test',
+                 "42",
+                 check,
+                 lambda x: int(x) + 12)
+
+        opts.Add('A',
+                 'a - alpha test',
+                 "42",
+                 check,
+                 lambda x: int(x) + 12)
+
+        env = Environment()
+        opts.Update(env, {})
+
+        expect = """\
+ANSWER 42 54 THE answer to THE question
+B 42 54 b - alpha test
+A 42 54 a - alpha test
+"""
+
+        text = opts.GenerateHelpText(env)
+        assert text == expect, text
+
+        expectAlpha = """\
+A 42 54 a - alpha test
+ANSWER 42 54 THE answer to THE question
+B 42 54 b - alpha test
+"""
+        text = opts.GenerateHelpText(env, sort=cmp)
+        assert text == expectAlpha, text
+
+
+    
         
 if __name__ == "__main__":
     suite = unittest.makeSuite(OptionsTestCase, 'test_')

diff --git a/src/engine/SCons/Options/__init__.py b/src/engine/SCons/Options/__init__.py
index fdaee920ae28568f93cb7f4ee7318c998883d8fc..f5f1b8dbb626f9813089eae4b00c1f83fa058763 100644 (file)
--- a/src/engine/SCons/Options/__init__.py
+++ b/src/engine/SCons/Options/__init__.py
@@ -30,6 +30,7 @@ customizable variables to an SCons build.
 __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
 
 import os.path
+import string
 
 import SCons.Errors
 import SCons.Util
@@ -223,11 +224,17 @@ class Options:
         else:
             options = self.options
 
-        for option in options:
-            help_text = help_text + '\n%s: %s\n    default: %s\n'%(option.key, option.help, option.default)
-            if env.has_key(option.key):
-                help_text = help_text + '    actual: %s\n'%env.subst('${%s}'%option.key)
+        def format(opt, self=self, env=env):
+            if env.has_key(opt.key):
+                actual = env.subst('${%s}' % opt.key)
             else:
-                help_text = help_text + '    actual: None\n'
+                actual = None
+            return self.FormatOptionHelpText(env, opt.key, opt.help, opt.default, actual)
+        lines = filter(None, map(format, options))
 
-        return help_text
+        return string.join(lines, '')
+
+    format = '\n%s: %s\n    default: %s\n    actual: %s\n'
+
+    def FormatOptionHelpText(self, env, key, help, default, actual):
+        return self.format % (key, help, default, actual)