Add an argument for sorting Options help text.

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

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index a778c388f0f70d9a349261c3b3df84607b6c55dc..32d4bfbf91f71cc13444566070a4f11b1a477f0f 100644 (file)
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2938,15 +2938,30 @@ opts.Save('options.cache', env)
 .EE
 
 .TP
-.RI GenerateHelpText( env )
+.RI GenerateHelpText( env ", [" sort ])
 This generates help text documenting the customizable construction
 variables suitable to passing in to the Help() function. 
 .I env
 is the construction environment that will be used to get the actual values
-of customizable variables. Example:
+of customizable variables. Calling with 
+an optional
+.I sort
+function
+will cause the output to be sorted
+by the specified argument.
+The specific
+.I sort
+function
+should take two arguments
+and return
+-1, 0 or 1
+(like the standard Python
+.I cmp
+function).
 
 .ES
 Help(opts.GenerateHelpText(env))
+Help(opts.GenerateHelpText(env, sort=cmp))
 .EE
 
 The text based SConscript file is executed as a Python script, and the

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 76ac21f71ad2fe7537a1a725888126fe89baa78e..04b543cee6fd222dac8fc5d52bd47e5105c74ae8 100644 (file)
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -29,6 +29,11 @@ RELEASE 0.14 - XXX
   - Pass an Environment to the Options validator method, and
     add an Options.Save() method.
 
+  From Steve Christensen:
+
+  - Add an optional sort function argument to the GenerateHelpText()
+    Options function.
+
   From Steven Knight:
 
   - Add support for Java (javac and jar).

diff --git a/src/engine/SCons/Options.py b/src/engine/SCons/Options.py
index d43be28768d040be46e697222d17b87c02090215..2aae5fc244dbc7dccd60ddbb6256d4b8d54e8f54 100644 (file)
--- a/src/engine/SCons/Options.py
+++ b/src/engine/SCons/Options.py
@@ -170,7 +170,7 @@ class Options:
         except IOError, x:
             raise SCons.Errors.UserError, 'Error writing options to file: %s\n%s' % (filename, x)
 
-    def GenerateHelpText(self, env):
+    def GenerateHelpText(self, env, sort=None):
         """
         Generate the help text for the options.
 
@@ -179,7 +179,13 @@ class Options:
 
         help_text = ""
 
-        for option in self.options:
+        if sort:
+            options = self.options[:]
+            options.sort(lambda x,y,func=sort: func(x.key,y.key))
+        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)

diff --git a/src/engine/SCons/OptionsTests.py b/src/engine/SCons/OptionsTests.py
index 70207878aa8db78adabcd08bc5efea91e4538c51..491845ef684d39a8de96b0105676a0fcea0cd725 100644 (file)
--- a/src/engine/SCons/OptionsTests.py
+++ b/src/engine/SCons/OptionsTests.py
@@ -71,7 +71,7 @@ class OptionsTestCase(unittest.TestCase):
         assert o.default == None
         assert o.validater == None
         assert o.converter == None
-       assert o.should_save == 0
+        assert o.should_save == 0
 
         o = opts.options[1]
         assert o.key == 'ANSWER'
@@ -172,6 +172,18 @@ class OptionsTestCase(unittest.TestCase):
                  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, {})
 
@@ -179,12 +191,36 @@ class OptionsTestCase(unittest.TestCase):
 ANSWER: THE answer to THE question
     default: 42
     actual: 54
+
+B: b - alpha test
+    default: 42
+    actual: 54
+
+A: a - alpha test
+    default: 42
+    actual: 54
 """
 
         text = opts.GenerateHelpText(env)
         assert text == expect, text
+
+        expectAlpha = """
+A: a - alpha test
+    default: 42
+    actual: 54
+
+ANSWER: THE answer to THE question
+    default: 42
+    actual: 54
+
+B: b - alpha test
+    default: 42
+    actual: 54
+"""
+        text = opts.GenerateHelpText(env, sort=cmp)
+        assert text == expectAlpha, text
         
 if __name__ == "__main__":
     suite = unittest.makeSuite(OptionsTestCase, 'test_')
     if not unittest.TextTestRunner().run(suite).wasSuccessful():
-       sys.exit(1)
+        sys.exit(1)

diff --git a/test/Options.py b/test/Options.py
index 57424076e546ad5c66219694d87c6e6a4797dd5c..7d850767110c3e2e42a44bd4ee79e97388d7a34a 100644 (file)
--- a/test/Options.py
+++ b/test/Options.py
@@ -258,4 +258,54 @@ test.run(arguments='"DEBUG_BUILD=0"')
 check(['0','0'])
 checkSave('options.saved',{'DEBUG_BUILD':'0'})
 
+test.write('SConstruct', """
+opts = Options('custom.py')
+opts.Add('RELEASE_BUILD',
+         'Set to 1 to build a release build',
+         0,
+         None,
+         int)
+
+opts.Add('DEBUG_BUILD',
+         'Set to 1 to build a debug build',
+         1,
+         None,
+         int)
+
+opts.Add('CC',
+         'The C compiler')
+
+opts.Add('UNSPECIFIED',
+         'An option with no value')
+
+env = Environment(options=opts)
+
+Help('Variables settable in custom.py or on the command line:\\n' + opts.GenerateHelpText(env,sort=cmp))
+
+""")
+
+test.run(arguments='-h',
+         stdout = """scons: Reading SConscript files ...
+scons: done reading SConscript files.
+Variables settable in custom.py or on the command line:
+
+CC: The C compiler
+    default: None
+    actual: %s
+
+DEBUG_BUILD: Set to 1 to build a debug build
+    default: 1
+    actual: 0
+
+RELEASE_BUILD: Set to 1 to build a release build
+    default: 0
+    actual: 1
+
+UNSPECIFIED: An option with no value
+    default: None
+    actual: None
+
+Use scons -H for help about command-line options.
+"""%cc)
+
 test.pass_test()