Implement RFC 71: EnumView.matches.

Author: wanda-phi

amaranth/lib/enum.py

@@ -313,6 +313,22 @@ def __ne__(self, other):
                             "the same enum type")
         return self.as_value() != other.as_value()
 
+    def matches(self, *patterns):
+        """Pattern matching.
+
+        Matches against a set of patterns, which must be values of the same enum as the view.
+
+        Returns
+        -------
+        :class:`Value`, :py:`unsigned(1)`
+        """
+        patterns = tuple(patterns)
+        for pattern in patterns:
+            if not isinstance(pattern, self.__enum):
+                raise TypeError(f"a pattern must be an enum value of the same type as the "
+                                f"EnumView ({self.__enum.__qualname__}), not {pattern!r}")
+        return self.__target.matches(*patterns)
+
     def __repr__(self):
         return f"{type(self).__qualname__}({self.__enum.__qualname__}, {self.__target!r})"
 

docs/changes.rst

@@ -23,6 +23,14 @@ Version 0.6.0 (unreleased)
 ==========================
 
 
+Implemented RFCs
+----------------
+
+.. _RFC 71: https://amaranth-lang.org/rfcs/0071-enumview-matches.html
+
+* `RFC 71`_: ``EnumView.matches``
+
+
 Language changes
 ----------------
 
@@ -45,6 +53,7 @@ Standard library changes
 .. currentmodule:: amaranth.lib
 
 * Added: :py:`payload_init=` argument in :class:`amaranth.lib.stream.Signature`.
+* Added: :meth:`enum.EnumView.matches`. (`RFC 71`_)
 * Changed: (deprecated in 0.5.1) providing :meth:`io.PortLike.__add__` is now mandatory. (`RFC 69`_)
 * Removed: (deprecated in 0.5.0) :mod:`amaranth.lib.coding`. (`RFC 63`_)
 

tests/test_lib_enum.py

@@ -147,6 +147,7 @@ class EnumA(Enum, shape=signed(4)):
         class EnumB(Enum, shape=signed(4)):
             C = 0
             D = 5
+            E = 7
         a = Signal(EnumA)
         b = Signal(EnumB)
         c = Signal(EnumA)
@@ -201,6 +202,16 @@ class EnumB(Enum, shape=signed(4)):
         self.assertRepr(a == EnumA.B, "(== (sig a) (const 4'sd-3))")
         self.assertRepr(EnumA.B == a, "(== (sig a) (const 4'sd-3))")
         self.assertRepr(a != EnumA.B, "(!= (sig a) (const 4'sd-3))")
+        self.assertRepr(b.matches(EnumB.C, EnumB.D), """
+            (r| (cat
+                (== (sig b) (const 1'd0))
+                (== (sig b) (const 3'd5))
+            ))
+        """)
+        with self.assertRaisesRegex(TypeError,
+                r"^a pattern must be an enum value of the same type as the EnumView \(.*EnumB\), "
+                r"not .*$"):
+            b.matches(EnumA.A)
 
     def test_flag_view(self):
         class FlagA(Flag, shape=unsigned(4)):