From f3085c3248737bfeefb249fdea4fd159e4d080ef Mon Sep 17 00:00:00 2001
From: Ioannis Filippidis <jfilippidis@gmail.com>
Date: Sun, 14 Nov 2021 04:30:54 +0100
Subject: [PATCH] API: support roots as `dict` in `dump()`, `load()`

for readability, maintainability. Documents
the recent changes to the JSON and Pickle interfaces.
These changes are arranged as separate commits
in order to group the changes by the filetype of
the interface being changed.
---
 README.md                |  2 +-
 dd/_abc.py               | 13 +++++++++----
 dd/autoref.py            |  6 +++++-
 dd/cudd.pyx              | 12 ++++++++++--
 examples/json_example.py |  7 ++++---
 5 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index f169199b..86c8d242 100644
--- a/README.md
+++ b/README.md
@@ -134,7 +134,7 @@ for d in bdd.pick_iter(u):
 n = bdd.count(u)
 # write to and load from JSON file
 filename = 'bdd.json'
-bdd.dump(filename, roots=[u])
+bdd.dump(filename, roots=dict(res=u))
 other_bdd = BDD()
 roots = other_bdd.load(filename)
 print(other_bdd.vars)
diff --git a/dd/_abc.py b/dd/_abc.py
index f60652a5..ce0dcde5 100644
--- a/dd/_abc.py
+++ b/dd/_abc.py
@@ -241,11 +241,12 @@ def dump(
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for Pickle: `dict` that maps
+              names (as `str`) to nodes
         """
 
-    # revise this method to return roots as `list` or
-    # named nodes as `dict`
     def load(self, filename, levels=True):
         """Load nodes from Pickle file `filename`.
 
@@ -255,7 +256,11 @@ def load(self, filename, levels=True):
 
         @type filename: `str`
         @return: roots of the loaded BDDs
-        @rtype: `list` of nodes
+        @rtype: depends on the contents of the file,
+            either:
+            - `dict` that maps names (as `str`)
+              to nodes, or
+            - `list` of nodes
         """
 
     @property
diff --git a/dd/autoref.py b/dd/autoref.py
index bedf9aaf..886e63ce 100644
--- a/dd/autoref.py
+++ b/dd/autoref.py
@@ -240,7 +240,11 @@ def dump(self, filename, roots=None,
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for JSON or Pickle:
+              `dict` that maps names (as `str`)
+              to nodes
         """
         # The method's docstring is a slight modification
         # of the docstring of the method `dd._abc.BDD.dump`.
diff --git a/dd/cudd.pyx b/dd/cudd.pyx
index a5c3679d..ec0e03e3 100644
--- a/dd/cudd.pyx
+++ b/dd/cudd.pyx
@@ -1822,7 +1822,11 @@ cdef class BDD:
 
         @type filename: `str`
         @type filetype: `str`, e.g., `"pdf"`
-        @type roots: container of nodes
+        @type roots:
+            - `list` of nodes, or
+            - for JSON:
+              `dict` that maps names (as `str`)
+              to nodes
         """
         if filetype is None:
             name = filename.lower()
@@ -1917,7 +1921,11 @@ cdef class BDD:
             where the BDD is loaded
         @type filename: `str`
         @return: roots of loaded BDDs
-        @rtype: `list` of `Function`
+        @rtype: depends on the contents of the file,
+            either:
+            - `dict` that maps names (as `str`)
+              to nodes (as `Function`), or
+            - `list` of `Function`
         """
         if filename.lower().endswith('.dddmp'):
             r = self._load_dddmp(filename)
diff --git a/examples/json_example.py b/examples/json_example.py
index a9acfbc5..305f575e 100644
--- a/examples/json_example.py
+++ b/examples/json_example.py
@@ -14,15 +14,16 @@ def dump_bdd_as_json(filename):
     bdd = _bdd.BDD()
     bdd.declare('x', 'y', 'z')
     u = bdd.add_expr(r'(x /\ y) \/ ~ z')
-    bdd.dump(filename, [u])
+    roots = dict(u=u)
+    bdd.dump(filename, roots)
     print(f'Dumped BDD: {u}')
 
 
 def load_bdd_from_json(filename):
     """Load a BDD from a JSON file."""
     bdd = _bdd.BDD()
-    u, = bdd.load(filename)
-    print(f'Loaded BDD: {u}')
+    roots = bdd.load(filename)
+    print(f'Loaded BDD: {roots}')
 
 
 if __name__ == '__main__':