From: stevenknight Date: Thu, 12 Aug 2004 22:19:56 +0000 (+0000) Subject: Add a Flatten() function to help the transition to Builders returning lists. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=3fb2348bb3ffa1b65bfbd16ce2266b35961a6770;p=scons.git Add a Flatten() function to help the transition to Builders returning lists. git-svn-id: http://scons.tigris.org/svn/scons/trunk@1026 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 957853e9..64756e92 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 @@ -2753,6 +2778,40 @@ derived files that have not yet been built. foo = env.FindFile('foo', ['dir1', 'dir2']) .EE +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.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 ", [" ... ]) diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 1c1829df..45d35b91 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 e38ebbb2..fc4dba05 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 1b2ceecc..e8f3cd84 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 074477ff..3146a9c3 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 00000000..7679bdb0 --- /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()