From 96e059857c7e21787bc2b4916acca60042881fee Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 4 Aug 2019 13:11:10 -0600 Subject: Update Dictionary documentation to match implementation [ci skip] Dictionary is now described as returning a dict only if called with no arguments; if called with arguments it returns a string or list of strings (matching the implmenentation). Note env.Dump() only takes zero arguments or one, it it not documented as taking the multiple keys, so there's less ambiguity with it. Some examples twiddled a little, and in a couple of cases Dictionary is not used any longer - we might as well just index into the construction environment since that works. Fixes #3156 Signed-off-by: Mats Wichmann --- doc/generated/functions.gen | 14 +++++----- doc/man/scons.xml | 59 ++++++++++++++++++++++------------------ doc/user/environments.xml | 19 ++++++++++--- src/engine/SCons/Environment.py | 43 +++++++++++++++++++++-------- src/engine/SCons/Environment.xml | 14 +++++----- 5 files changed, 94 insertions(+), 55 deletions(-) diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 9bed358..c446a44 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -1333,11 +1333,11 @@ env.Depends(bar, installed_lib) Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. +containing construction variables in the environment. +If there are any arguments specified, +only the values of the specified construction +variables are returned as a string (if one +argument) or as a list of strings. @@ -1345,8 +1345,8 @@ Example: -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +cvars = env.Dictionary() +cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 542ac9d..e610386 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2577,8 +2577,8 @@ object_files.extend(Object('bar.c')) The path name for a Node's file may be used -by passing the Node to the Python-builtin -str() +by passing the Node to Python's builtin +str function: @@ -3119,11 +3119,12 @@ defined construction variables: method of the construction environment: -dict = env.Dictionary() -dict["CC"] = "cc" +cvars = env.Dictionary() +cvars["CC"] = "cc" -or using the [] operator: +or using the key lookup operator [] +directly on the construction environment: env["CC"] = "cc" @@ -6315,7 +6316,8 @@ might not exist argument is the construction environment for the scan. Fetch values from it using the env.Dictionary() -method. +method or using the key lookup operator +directly on the construction environment. The path @@ -6771,7 +6773,7 @@ env['BUILDERS]['PDFBuilder'] = bld Defining Your Own Scanner Object -The following example shows an extremely simple scanner (the +The following example shows adding an extremely simple scanner (the kfile_scan() function) that doesn't use a search path at all @@ -6796,8 +6798,10 @@ kscan = Scanner(name = 'kfile', function = kfile_scan, argument = None, skeys = ['.k']) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [kscan]) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(kscan) +env = Environment(SCANNERS=scanners) env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') @@ -6814,7 +6818,8 @@ you can use the function of your current Environment in order to create nodes on the fly from a sequence of file names with relative paths. -Here is a similar but more complete example that searches +Here is a similar but more complete example that adds +a scanner which searches a path of directories (specified as the MYPATH @@ -6840,15 +6845,16 @@ def my_scan(node, env, path, arg): break return env.File(results) -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = FindPathDirs('MYPATH') +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=FindPathDirs('MYPATH') ) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner], - MYPATH = ['incs']) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(scanner) +env = Environment(SCANNERS=scanners, MYPATH=['incs']) env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') @@ -6861,8 +6867,8 @@ that will return a list of directories specified in the $MYPATH construction variable. It lets SCons detect the file -incs/foo.inc -, even if +incs/foo.inc, +even if foo.x contains the line include foo.inc @@ -6883,17 +6889,18 @@ def pf(env, dir, target, source, arg): results.append(top_dir + os.sep + p) return results -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = pf +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=pf ) -Creating a Hierarchical Build + +Creating a Hierarchical Build Notice that the file names specified in a subdirectory's SConscript diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 65eed72..3f1f142 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -645,8 +645,9 @@ print("CC is: %s"%env['CC']) - A construction environment, however, - is actually an object with associated methods, etc. + A construction environment + is actually an object with associated methods and + attributes. If you want to have direct access to only the dictionary of construction variables, you can fetch this using the &Dictionary; method: @@ -656,9 +657,9 @@ print("CC is: %s"%env['CC']) env = Environment(FOO = 'foo', BAR = 'bar') -dict = env.Dictionary() +cvars = env.Dictionary() for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: - print("key = %s, value = %s" % (key, dict[key])) + print("key = %s, value = %s" % (key, cvars[key])) @@ -698,6 +699,16 @@ for item in sorted(env.Dictionary().items()): print("construction variable = '%s', value = '%s'" % item) + + It should be noted that for the previous example, there is actually + an environment method that does the same thing more simply, + and tries to format it nicely as well: + + +env = Environment() +print(env.Dump()) + +
diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py index 5faa2d0..2e1e742 100644 --- a/src/engine/SCons/Environment.py +++ b/src/engine/SCons/Environment.py @@ -1493,8 +1493,14 @@ class Base(SubstitutionEnvironment): self.copy_from_cache = copy_function + def Detect(self, progs): """Return the first available program in progs. + + :param progs: one or more command names to check for + :type progs: str or list + :returns str: first name from progs that can be found. + """ if not SCons.Util.is_List(progs): progs = [ progs ] @@ -1503,7 +1509,17 @@ class Base(SubstitutionEnvironment): if path: return prog return None + def Dictionary(self, *args): + """Return construction variables from an environment. + + :param *args: (optional) variable names to look up + :returns: if args omitted, the dictionary of all constr. vars. + If one arg, the corresponding value is returned. + If more than one arg, a list of values is returned. + :raises KeyError: if any of *args is not in the construction env. + + """ if not args: return self._dict dlist = [self._dict[x] for x in args] @@ -1511,23 +1527,28 @@ class Base(SubstitutionEnvironment): dlist = dlist[0] return dlist - def Dump(self, key = None): - """ - Using the standard Python pretty printer, return the contents of the - scons build environment as a string. - If the key passed in is anything other than None, then that will - be used as an index into the build environment dictionary and - whatever is found there will be fed into the pretty printer. Note - that this key is case sensitive. + def Dump(self, key=None): + """ Return pretty-printed string of construction variables. + + :param key: if None, format the whole dict of variables. + Else look up and format just the value for key. + """ import pprint pp = pprint.PrettyPrinter(indent=2) if key: - dict = self.Dictionary(key) + cvars = self.Dictionary(key) else: - dict = self.Dictionary() - return pp.pformat(dict) + cvars = self.Dictionary() + + # TODO: pprint doesn't do a nice job on path-style values + # if the paths contain spaces (i.e. Windows), because the + # algorithm tries to break lines on spaces, while breaking + # on the path-separator would be more "natural". Is there + # a better way to format those? + return pp.pformat(cvars) + def FindIxes(self, paths, prefix, suffix): """ diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 46a00d2..3f12b4f 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1325,11 +1325,11 @@ env.Depends(bar, installed_lib) Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. +containing construction variables in the environment. +If there are any arguments specified, +only the values of the specified construction +variables are returned as a string (if one +argument) or as a list of strings. @@ -1337,8 +1337,8 @@ Example: -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +cvars = env.Dictionary() +cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') -- cgit v0.12