Extend `Environment.Dump()` to select serialization format

Environment.Dump() produces pretty-printable results only, so the
usefulness of this method is limited to debugging purposes.

The existing method is extended to allow selecting a serialization
format to use via a `format` parameter. Namely, it's now possible to
serialize variables as a JSON-formatted string, which makes it possible
for automated external tools to inspect the environment more easily.

4 files changed, 66 insertions, 12 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index ecf3255..4774881 100755
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -54,6 +54,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Reorganized source tree. Moved src/engine/SCons to SCons to be more in line with current Python source
       tree organization practices.
 
+  From Andrii Doroshenko:
+    - Extended `Environment.Dump()` to select a format to serialize construction variables (pretty, json).
+
   From Jeremy Elson:
     - Updated design doc to use the correct syntax for Depends()
 
diff --git a/SCons/Environment.py b/SCons/Environment.py
index 0b4be1b..cd52ee5 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -1517,26 +1517,42 @@ class Base(SubstitutionEnvironment):
         return dlist
 
 
-    def Dump(self, key=None):
-        """ Return pretty-printed string of construction variables.
+    def Dump(self, key=None, format='pretty'):
+        """ Serialize the construction variables to a string.
 
         :param key: if None, format the whole dict of variables.
             Else look up and format just the value for key.
+            
+        :param format: specify the format of the variables to be serialized:
+            - pretty: pretty-printed string.
+            - json: JSON-formatted string.
 
         """
-        import pprint
-        pp = pprint.PrettyPrinter(indent=2)
         if key:
             cvars = self.Dictionary(key)
         else:
             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)
+        fmt = format.lower()
+
+        if fmt == 'pretty':
+            import pprint
+            pp = pprint.PrettyPrinter(indent=2)
+
+            # 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)
+
+        elif fmt == 'json':
+            import json
+            def non_serializable(obj):
+                return str(type(obj).__qualname__)
+            return json.dumps(cvars, indent=4, default=non_serializable)
+        else:
+            raise ValueError("Unsupported serialization format: %s." % fmt)
 
 
     def FindIxes(self, paths, prefix, suffix):
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index d13d560..898dc5d 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -1393,11 +1393,34 @@ for more information.
 
 <scons_function name="Dump">
 <arguments signature="env">
-([key])
+([key], [format])
 </arguments>
 <summary>
 <para>
-Returns a pretty printable representation of the environment.
+Serializes the construction variables to a string.
+The method supports the following formats specified by
+<parameter>format</parameter>:
+<variablelist>
+<varlistentry>
+<term><literal>pretty</literal></term>
+<listitem>
+<para>
+Returns a pretty printable representation of the environment (if
+<parameter>format</parameter>
+is not specified, this is the default).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>json</literal></term>
+<listitem>
+<para>
+Returns a JSON-formatted string representation of the environment.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
 <varname>key</varname>,
 if not
 <literal>None</literal>,
diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py
index ef12a6f..6dcf3c1 100644
--- a/SCons/EnvironmentTests.py
+++ b/SCons/EnvironmentTests.py
@@ -2941,6 +2941,18 @@ def generate(env):
         assert env.Dump('FOO') == "'foo'", env.Dump('FOO')
         assert len(env.Dump()) > 200, env.Dump()    # no args version
 
+        assert env.Dump('FOO', 'json') == '"foo"'    # JSON key version
+        import json
+        env_dict = json.loads(env.Dump(format = 'json'))
+        assert env_dict['FOO'] == 'foo'    # full JSON version
+
+        try:
+            env.Dump(format = 'markdown')
+        except ValueError as e:
+            assert str(e) == "Unsupported serialization format: markdown."
+        else:
+            self.fail("Did not catch expected ValueError.")
+
     def test_Environment(self):
         """Test the Environment() method"""
         env = self.TestEnvironment(FOO = 'xxx', BAR = 'yyy')