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 <mats@linux.com>

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)
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 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.
 </para>
 
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1345,8 +1345,8 @@ Example:
 </para>
 
 <example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
-dict = env.Dictionary()
-cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
+cvars = env.Dictionary()
+cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 </example_commands>
 </listitem>
   </varlistentry>
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'))
 </literallayout>
 
 <para>The path name for a Node's file may be used
-by passing the Node to the Python-builtin
-<function>str()</function>
+by passing the Node to Python's builtin
+<function>str</function>
 function:</para>
 
 <literallayout class="monospaced">
@@ -3119,11 +3119,12 @@ defined construction variables:</para>
 method of the construction environment:</para>
 
 <literallayout class="monospaced">
-dict = env.Dictionary()
-dict["CC"] = "cc"
+cvars = env.Dictionary()
+cvars["CC"] = "cc"
 </literallayout>
 
-<para>or using the [] operator:</para>
+<para>or using the key lookup operator <literal>[]</literal>
+directly on the construction environment:</para>
 
 <literallayout class="monospaced">
 env["CC"] = "cc"
@@ -6315,7 +6316,8 @@ might not exist
 argument is the construction environment for the scan.
 Fetch values from it using the
 <emphasis role="bold">env.Dictionary()</emphasis>
-method.</para>
+method or using the key lookup operator
+directly on the construction environment.</para>
 
 <para>The
 <emphasis role="bold">path</emphasis>
@@ -6771,7 +6773,7 @@ env['BUILDERS]['PDFBuilder'] = bld
 
 <refsect2 id='defining_your_own_scanner_object'><title>Defining Your Own Scanner Object</title>
 
-<para>The following example shows an extremely simple scanner (the
+<para>The following example shows adding an extremely simple scanner (the
 <emphasis role="bold">kfile_scan</emphasis>()
 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 &lt; $SOURCES &gt; $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.</para>
 
-<para>Here is a similar but more complete example that searches
+<para>Here is a similar but more complete example that adds
+a scanner which searches
 a path of directories
 (specified as the
 <emphasis role="bold">MYPATH</emphasis>
@@ -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 &lt; $SOURCES &gt; $TARGET')
 </programlisting>
@@ -6861,8 +6867,8 @@ that will return a list of directories
 specified in the
 <emphasis role="bold">$MYPATH</emphasis>
 construction variable. It lets SCons detect the file
-<emphasis role="bold">incs/foo.inc</emphasis>
-, even if
+<emphasis role="bold">incs/foo.inc</emphasis>,
+even if
 <emphasis role="bold">foo.x</emphasis>
 contains the line
 <emphasis role="bold">include foo.inc</emphasis>
@@ -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
                  )
 </programlisting>
 
 </refsect2>
 
-<refsect2 id='creating_a_hierarchical_build'><title>Creating a Hierarchical Build</title>
+<refsect2 id='creating_a_hierarchical_build'>
+<title>Creating a Hierarchical Build</title>
 
 <para>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'])
 
       <para>
 
-      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'])
       <scons_example name="environments_ex6b">
          <file name="SConstruct" printme="1">
 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]))
          </file>
       </scons_example>
 
@@ -698,6 +699,16 @@ for item in sorted(env.Dictionary().items()):
     print("construction variable = '%s', value = '%s'" % item)
       </sconstruct>
 
+      <para>
+      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:
+      </para>
+      <sconstruct>
+env = Environment()
+print(env.Dump())
+      </sconstruct>
+
     </section>
 
     <section>
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)
 <summary>
 <para>
 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.
 </para>
 
 <para>
@@ -1337,8 +1337,8 @@ Example:
 </para>
 
 <example_commands>
-dict = env.Dictionary()
-cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
+cvars = env.Dictionary()
+cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 </example_commands>
 </summary>
 </scons_function>