6 files changed, 153 insertions, 3 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 957853e..64756e9 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -1191,11 +1191,36 @@ by avoiding having to specify
 a platform-specific object suffix
 when calling the Program() builder method.
 
-(Note that Builder calls will "flatten" the lists
-the source and target file list,
+Note that Builder calls will automatically "flatten"
+the source and target file lists,
 so it's all right to have the bar_obj list
 return by the StaticObject() call
-in the middle of the source file list.)
+in the middle of the source file list.
+If you need to manipulate a list of lists returned by Builders
+directly using Python,
+you can either build the list by hand:
+
+.ES
+foo = Object('foo.c')
+bar = Object('bar.c')
+objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
+for object in objects:
+    print str(object)
+.EE
+
+Or you can use the
+.BR Flatten ()
+supplied by scons
+to create a list containing just the Nodes,
+which may be more convenient:
+
+.ES
+foo = Object('foo.c')
+bar = Object('bar.c')
+objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
+for object in objects:
+    print str(object)
+.EE
 
 The path name for a Node's file may be used
 by passing the Node to the Python-builtin
@@ -2755,6 +2780,40 @@ foo = env.FindFile('foo', ['dir1', 'dir2'])
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI Flatten( sequence )
+.TP
+.RI env.Flatten( sequence )
+Takes a sequence (that is, a Python list or tuple)
+that may contain nested sequences
+and returns a flattened list containing
+all of the individual elements in any sequence.
+This can be helpful for collecting
+the lists returned by calls to Builders;
+other Builders will automatically
+flatten lists specified as input,
+but direct Python manipulation of
+these lists does not:
+
+.ES
+foo = Object('foo.c')
+bar = Object('bar.c')
+
+# Because `foo' and `bar' are lists returned by the Object() Builder,
+# `objects' will be a list containing nested lists:
+objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
+
+# Passing such a list to another Builder is all right because
+# the Builder will flatten the list automatically:
+Program(source = objects)
+
+# If you need to manipulate the list directly using Python, you need to
+# call Flatten() yourself, or otherwise handle nested lists:
+for object in Flatten(objects):
+    print str(object)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI GetBuildPath( file ", [" ... ])
 .TP
 .RI env.GetBuildPath( file ", [" ... ])
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 1c1829d..45d35b9 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -152,6 +152,9 @@ RELEASE 0.96 - XXX
     one target.  This keeps things consistent and easier to program to
     across platforms.
 
+  - Add a Flatten() function to make it easier to deal with the Builders
+    all returning lists of targets, not individual targets.
+
   From Chris Murray:
 
   - Add a .win32 attribute to force file names to expand with
diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py
index e38ebbb..fc4dba0 100644
--- a/src/engine/SCons/Environment.py
+++ b/src/engine/SCons/Environment.py
@@ -1058,6 +1058,9 @@ class Base:
         nodes = self.arg2nodes(dirs, self.fs.Dir)
         return SCons.Node.FS.find_file(file, nodes, self.fs.File)
 
+    def Flatten(self, sequence):
+        return SCons.Util.flatten(sequence)
+
     def GetBuildPath(self, files):
         result = map(str, self.arg2nodes(files, self.fs.Entry))
         if SCons.Util.is_List(files):
diff --git a/src/engine/SCons/EnvironmentTests.py b/src/engine/SCons/EnvironmentTests.py
index 1b2ceec..e8f3cd8 100644
--- a/src/engine/SCons/EnvironmentTests.py
+++ b/src/engine/SCons/EnvironmentTests.py
@@ -2044,6 +2044,14 @@ class EnvironmentTestCase(unittest.TestCase):
 
         # XXX
 
+    def test_Flatten(self):
+        """Test the Flatten() method"""
+        env = Environment()
+        l = env.Flatten([1])
+        assert l == [1]
+        l = env.Flatten([1, [2, [3, [4]]]])
+        assert l == [1, 2, 3, 4], l
+
     def test_GetBuildPath(self):
         """Test the GetBuildPath() method."""
         env = Environment(MAGIC = 'xyzzy')
diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py
index 074477f..3146a9c 100644
--- a/src/engine/SCons/Script/SConscript.py
+++ b/src/engine/SCons/Script/SConscript.py
@@ -612,6 +612,7 @@ GlobalDefaultEnvironmentFunctions = [
     'Execute',
     'File',
     'FindFile',
+    'Flatten',
     'GetBuildPath',
     'Ignore',
     'Install',
diff --git a/test/Flatten.py b/test/Flatten.py
new file mode 100644
index 0000000..7679bdb
--- /dev/null
+++ b/test/Flatten.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+#
+# __COPYRIGHT__
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
+
+"""
+Test that the Flatten() function is available and works.
+"""
+
+import TestSCons
+
+test = TestSCons.TestSCons()
+
+test.subdir('work')
+
+test.write(['work', 'SConstruct'], """
+def cat(env, source, target):
+    target = str(target[0])
+    source = map(str, source)
+    f = open(target, "wb")
+    for src in source:
+        f.write(open(src, "rb").read())
+    f.close()
+env = Environment(BUILDERS={'Cat':Builder(action=cat)})
+f1 = env.Cat('../file1.out', 'file1.in')
+f2 = env.Cat('../file2.out', ['file2a.in', 'file2b.in'])
+print map(str, Flatten(['begin', f1, 'middle', f2, 'end']))
+print map(str, env.Flatten([f1, [['a', 'b'], 'c'], f2]))
+SConscript('SConscript', "env")
+""")
+
+test.write(['work', 'SConscript'], """
+Import("env")
+print Flatten([1, [2, 3], 4])
+print env.Flatten([[[[1], 2], 3], 4])
+""")
+
+test.write('file1.in', "file1.in\n")
+test.write('file2a.in', "file2a.in\n")
+test.write('file2b.in', "file2b.in\n")
+
+expect = """\
+['begin', '%s', 'middle', '%s', 'end']
+['%s', 'a', 'b', 'c', '%s']
+[1, 2, 3, 4]
+[1, 2, 3, 4]
+""" % (test.workpath('file1.out'), test.workpath('file2.out'),
+       test.workpath('file1.out'), test.workpath('file2.out'))
+
+test.run(chdir = "work",
+         arguments = ".",
+         stdout = test.wrap_stdout(read_str = expect,
+                                   build_str = "scons: `.' is up to date.\n"))
+
+test.pass_test()