remove eval_stmt add run_stmt_fallback (#149)

We have `eval_stmt` and `run_stmt` which has been two confusing APIs.
The original intention was to separate the stage when registering the
source info (which we don't have yet), and when to actually lookup the
registery. I think this is not necessary now, to change how to update
the source info just overload `run_stmt` otherwise update lookup
behaviour with `lookup_registry` or define fallback via
`run_stmt_fallback`

cc: @kaihsin

Author: Roger-luo

src/kirin/analysis/const/prop.py

@@ -48,7 +48,7 @@ def _try_eval_const_pure(
         try:
             _frame = self.interp.new_frame(frame.code)
             _frame.set_values(stmt.args, tuple(x.data for x in values))
-            value = self.interp.eval_stmt(_frame, stmt)
+            value = self.interp.run_stmt(_frame, stmt)
             if isinstance(value, tuple):
                 return tuple(JointResult(Value(each), Pure()) for each in value)
             elif isinstance(value, interp.ReturnValue):
@@ -64,7 +64,7 @@ def _try_eval_const_pure(
             pass
         return (self.bottom,)
 
-    def eval_stmt(
+    def run_stmt(
         self, frame: ForwardFrame[JointResult, ExtraFrameInfo], stmt: ir.Statement
     ) -> interp.StatementResult[JointResult]:
         if stmt.has_trait(ir.ConstantLike):

src/kirin/analysis/typeinfer/analysis.py

@@ -30,13 +30,9 @@ def _unwrap(self, value: types.TypeAttribute) -> types.TypeAttribute:
             return value.body
         return value
 
-    def eval_stmt(
+    def run_stmt_fallback(
         self, frame: ForwardFrame[types.TypeAttribute, None], stmt: ir.Statement
-    ) -> interp.StatementResult[types.TypeAttribute]:
-        method = self.lookup_registry(frame, stmt)
-        if method is not None:
-            return method(self, frame, stmt)
-
+    ) -> tuple[types.TypeAttribute, ...] | interp.SpecialResult[types.TypeAttribute]:
         resolve = TypeResolution()
         for arg, value in zip(stmt.args, frame.get_values(stmt.args)):
             resolve.solve(arg.type, value)

src/kirin/interp/base.py

@@ -198,7 +198,9 @@ def permute_values(
         return args
 
     def run_stmt(self, frame: FrameType, stmt: Statement) -> StatementResult[ValueType]:
-        """Run a statement within the current frame
+        """Run a statement within the current frame. This is the entry
+        point of running a statement. It will look up the statement implementation
+        in the dialect registry, or optionally call a fallback implementation.
 
         Args:
             frame: the current frame
@@ -208,8 +210,11 @@ def run_stmt(self, frame: FrameType, stmt: Statement) -> StatementResult[ValueTy
             StatementResult: the result of running the statement
 
         Note:
-            In the case of implementing the fallback, subclass this method,
-            and filter the statement type you want to handle.
+            Overload this method for the following reasons:
+            - to change the source tracking information
+            - to take control of how to run a statement
+            - to change the implementation lookup behavior that cannot acheive
+                by overloading [`lookup_registry`][kirin.interp.base.BaseInterpreter.lookup_registry]
 
         Example:
             * implement an interpreter that only handles MyStmt:
@@ -225,19 +230,32 @@ def run_stmt(self, frame: FrameType, stmt: Statement) -> StatementResult[ValueTy
 
         """
         # TODO: update tracking information
-        return self.eval_stmt(frame, stmt)
-
-    def eval_stmt(
-        self, frame: FrameType, stmt: Statement
-    ) -> StatementResult[ValueType]:
-        "simply evaluate a statement"
         method = self.lookup_registry(frame, stmt)
         if method is not None:
             try:
                 return method(self, frame, stmt)
             except InterpreterError as e:
                 return Err(e, self.state.frames)
 
+        return self.run_stmt_fallback(frame, stmt)
+
+    def run_stmt_fallback(
+        self, frame: FrameType, stmt: Statement
+    ) -> StatementResult[ValueType]:
+        """The fallback implementation of statements.
+
+        This is called when no implementation is found for the statement.
+
+        Args:
+            frame: the current frame
+            stmt: the statement to run
+
+        Returns:
+            StatementResult: the result of running the statement
+
+        Note:
+            Overload this method to provide a fallback implementation for statements.
+        """
         # NOTE: not using f-string here because 3.10 and 3.11 have
         #  parser bug that doesn't allow f-string in raise statement
         raise ValueError(