Add an argument for sorting Options help text.

5 files changed, 118 insertions, 6 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index a778c38..32d4bfb 100644
--- 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 76ac21f..04b543c 100644
--- 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 d43be28..2aae5fc 100644
--- 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 7020787..491845e 100644
--- 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 5742407..7d85076 100644
--- 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()