hdl.ir: rename .get_fragment() to .elaborate().

Closes #9.

nmigen/hdl/dsl.py

@@ -3,7 +3,7 @@ from collections.abc import Iterable
 from contextlib import contextmanager
 import warnings
 
-from ..tools import flatten, bits_for
+from ..tools import flatten, bits_for, deprecated
 from .ast import *
 from .ir import *
 from .xfrm import *
@@ -367,9 +367,15 @@ class Module(_ModuleBuilderRoot):
             self._statements.append(assign)
 
     def _add_submodule(self, submodule, name=None):
-        if not hasattr(submodule, "get_fragment"):
-            raise TypeError("Trying to add '{!r}', which does not implement .get_fragment(), as "
-                            "a submodule".format(submodule))
+        if not hasattr(submodule, "elaborate"):
+            if hasattr(submodule, "get_fragment"): # :deprecated:
+                warnings.warn("Adding '{!r}', which implements .get_fragment() but not "
+                              ".elaborate(), as a submodule. .get_fragment() is deprecated, "
+                              "and .elaborate() should be provided instead.".format(submodule),
+                              DeprecationWarning, stacklevel=2)
+            else:
+                raise TypeError("Trying to add '{!r}', which does not implement .elaborate(), as "
+                                "a submodule".format(submodule))
         self._submodules.append((submodule, name))
 
     def _add_domain(self, cd):
@@ -379,12 +385,20 @@ class Module(_ModuleBuilderRoot):
         while self._ctrl_stack:
             self._pop_ctrl()
 
-    def lower(self, platform):
+    @deprecated("`m.get_fragment(...)` is deprecated; use `m` instead")
+    def get_fragment(self, platform): # :deprecated:
+        return self.elaborate(platform)
+
+    @deprecated("`m.lower(...)` is deprecated; use `m` instead")
+    def lower(self, platform): # :deprecated:
+        return self.elaborate(platform)
+
+    def elaborate(self, platform):
         self._flush()
 
         fragment = Fragment()
         for submodule, name in self._submodules:
-            fragment.add_subfragment(submodule.get_fragment(platform), name)
+            fragment.add_subfragment(Fragment.get(submodule, platform), name)
         statements = SampleDomainInjector("sync")(self._statements)
         fragment.add_statements(statements)
         for signal, domain in self._driving.items():
@@ -392,5 +406,3 @@ class Module(_ModuleBuilderRoot):
         fragment.add_domains(self._domains)
         fragment.generated.update(self._generated)
         return fragment
-
-    get_fragment = lower

nmigen/hdl/ir.py

@@ -14,6 +14,14 @@ class DriverConflict(UserWarning):
 
 
 class Fragment:
+    @staticmethod
+    def get(obj, platform):
+        if isinstance(obj, Fragment):
+            return obj
+        if not hasattr(obj, "elaborate"): # :deprecated:
+            return Fragment.get(obj.get_fragment(platform), platform)
+        return Fragment.get(obj.elaborate(platform), platform)
+
     def __init__(self):
         self.ports = SignalDict()
         self.drivers = OrderedDict()
@@ -105,7 +113,7 @@ class Fragment:
             item, = path
             return self.generated[item]
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         return self
 
     def _merge_subfragment(self, subfragment):

nmigen/hdl/mem.py

@@ -91,7 +91,7 @@ class ReadPort:
         else:
             self.en = Const(1)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         f = Instance("$memrd",
             p_MEMID=self.memory,
             p_ABITS=self.addr.nbits,
@@ -154,7 +154,7 @@ class WritePort:
         self.en   = Signal(memory.width // granularity,
                            name="{}_w_en".format(memory.name))
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         f = Instance("$memwr",
             p_MEMID=self.memory,
             p_ABITS=self.addr.nbits,