Add Stack[] (#1259)

rocky · web-flow · commit db2f47923dfc · 2025-01-21T04:48:20.000-05:00
Start `Stack[]` builtin function. I hope more sometime after release.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -12,6 +12,7 @@ New Builtins
 * ``FormatValues``
 * ``SetEnvironment``
 * ``SequenceForm``
+* ``Stack``
 
 By `@davidar <https://github.com/davidar>`_:
 
diff --git a/SYMBOLS_MANIFEST.txt b/SYMBOLS_MANIFEST.txt
@@ -1120,7 +1120,7 @@ System`SquareSupersetEqual
 System`SquareUnion
 System`SquaredEuclideanDistance
 System`SquaresR
-System`Stacktrace
+System`Stack
 System`StandardDeviation
 System`StandardForm
 System`Star
diff --git a/mathics/builtin/evaluation.py b/mathics/builtin/evaluation.py
@@ -116,8 +116,8 @@ class Hold(Builtin):
     <url>:WMA link:https://reference.wolfram.com/language/ref/Hold.html</url>
 
     <dl>
-    <dt>'Hold[$expr$]'
-        <dd>prevents $expr$ from being evaluated.
+      <dt>'Hold[$expr$]'
+      <dd>prevents $expr$ from being evaluated.
     </dl>
 
     >> Attributes[Hold]
@@ -133,9 +133,9 @@ class HoldComplete(Builtin):
     <url>:WMA link:https://reference.wolfram.com/language/ref/HoldComplete.html</url>
 
     <dl>
-    <dt>'HoldComplete[$expr$]'
-        <dd>prevents $expr$ from being evaluated, and also prevents
-        'Sequence' objects from being spliced into argument lists.
+      <dt>'HoldComplete[$expr$]'
+      <dd>prevents $expr$ from being evaluated, and also prevents \
+         'Sequence' objects from being spliced into argument lists.
     </dl>
 
     >> Attributes[HoldComplete]
diff --git a/mathics/builtin/symbolic_history/__init__.py b/mathics/builtin/symbolic_history/__init__.py
@@ -0,0 +1,6 @@
+"""
+Symbolic Execution History
+
+In order to debug and understand program execution, the execution history can be saved.
+"""
+sort_order = "mathics.builtin.symbolic-execution-history"
diff --git a/mathics/builtin/symbolic_history/stack.py b/mathics/builtin/symbolic_history/stack.py
@@ -0,0 +1,66 @@
+# from mathics.core.atoms import Integer2
+from mathics.core.attributes import A_HOLD_ALL, A_HOLD_FIRST, A_PROTECTED
+from mathics.core.builtin import Builtin
+from mathics.core.evaluation import Evaluation
+from mathics.core.list import ListExpression
+
+# from mathics.core.systemsymbols import SymbolTrace
+from mathics.eval.symbolic_history.stack import eval_Stack, eval_Trace
+
+
+class Stack(Builtin):
+    """
+    <url>:WMA link:
+    https://reference.wolfram.com/language/ref/Stack.html</url>
+
+    <dl>
+      <dt>'Stack[]'
+      <dd>Print Mathics3 stack trace of evalutations leading to this point.
+    </dl>
+
+    >> f[g[1, Print[Stack[]] ; 2]]
+     = {f[g[1, Print[Stack[]] ; 2]], g[1, Print[Stack[]] ; 2], Print[Stack[]] ; 2, CompoundExpression, Print[Stack[]]}
+
+
+    The actual 'Stack[0]' call is hidden from the output; so when \
+    run on its own, nothing appears.
+
+    >> Stack[]
+     = {}
+    """
+
+    attributes = A_HOLD_FIRST | A_PROTECTED
+    summary_text = "print Mathics3 function stacktrace"
+
+    def eval(self, evaluation: Evaluation) -> ListExpression:
+        "Stack[]"
+
+        return eval_Stack()
+
+
+class Trace(Builtin):
+    """
+    <url>:WMA link:
+    https://reference.wolfram.com/language/ref/Trace.html</url>
+
+    <dl>
+      <dt>'Trace[$expr$]'
+      <dd>generate a list of all expressions used in the evaluation of $expr$.
+    </dl>
+
+    >> Trace[1 + 2]
+     = {1 + 2, 3}
+    """
+
+    attributes = A_HOLD_ALL | A_PROTECTED
+    summary_text = "list intermediary expressions in an evaluation"
+
+    def eval(self, expr, evaluation: Evaluation) -> ListExpression:
+        "Trace[expr__]"
+
+        # n = len(expr.elements)
+        # if n > 2:
+        #     evaluation.message("Trace", "nonopt", TraceSymbol, Integer2
+        #                        Expression[TraceSymbol]
+        #     return
+        return eval_Trace(expr, evaluation)
diff --git a/mathics/builtin/trace.py b/mathics/builtin/trace.py
@@ -22,7 +22,6 @@
 from time import time
 from typing import Callable
 
-import mathics.eval.trace
 import mathics.eval.tracing
 from mathics.core.attributes import A_HOLD_ALL, A_HOLD_ALL_COMPLETE, A_PROTECTED
 from mathics.core.builtin import Builtin
@@ -147,46 +146,6 @@ def eval(self, evaluation, options={}):
         return SymbolNull
 
 
-class Stacktrace(_TraceBase):
-    """
-    ## <url>:trace native symbol:</url>
-
-    <dl>
-      <dt>'Stacktrace[]'
-      <dd>Print Mathics3 stack trace of evaluations leading to this point
-    </dl>
-
-    To show the Mathics3 evaluation stack at the \
-    point where expression $expr$ is evaluated, wrap $expr$ inside '{$expr$ Stacktrace[]}[1]]' \
-    or something similar.
-
-    Here is a complete example. To show the evaluation stack when computing a homegrown \
-    factorial function:
-
-    >> F[0] := {1, Stacktrace[]}[[1]]; F[n_] := n * F[n-1]
-
-    >> F[3] (* See console log *)
-     = 6
-
-    The actual 'Stacktrace[0]' call is hidden from the output; so when \
-    run on its own, nothing appears.
-
-    >> Stacktrace[]
-
-    #> Clear[F]
-    """
-
-    summary_text = "print Mathics3 function stacktrace"
-
-    def eval(self, evaluation: Evaluation):
-        "Stacktrace[]"
-
-        # Use longer-form resolve call
-        # so a debugger can change this.
-        mathics.eval.trace.eval_Stacktrace()
-        return SymbolNull
-
-
 class TraceBuiltins(_TraceBase):
     """
     ## <url>:trace native symbol:</url>
@@ -433,8 +392,7 @@ def eval(self, expr, evaluation: Evaluation, options: dict):
             options["System`ShowTimeBySteps"] is SymbolTrue
         )
         try:
-            result = expr.evaluate(evaluation)
-            return result
+            return expr.evaluate(evaluation)
         except Exception:
             raise
         finally:
diff --git a/mathics/core/evaluation.py b/mathics/core/evaluation.py
@@ -124,6 +124,11 @@ def __init__(
         # status of last evaluate
         self.exc_result: Optional[Symbol] = self.SymbolNull
         self.last_eval = None
+
+        # A place for Trace and friend to store information about the
+        # last evaluation
+        self.trace_info: Optional[Any] = None
+
         # Used in ``mathics.builtin.numbers.constants.get_constant`` and
         # ``mathics.builtin.numeric.N``.
         self._preferred_n_method: List[str] = []
diff --git a/mathics/core/expression.py b/mathics/core/expression.py
@@ -1416,13 +1416,8 @@ def rules():
                 if not isinstance(result, EvalMixin):
                     return result, False
                 if result.sameQ(new):
-                    # Even though result and new may be the same,
-                    # new can be a Expression[SymbolConstant: System`List...]
-                    # while "result' might be ListExpression!?
-                    # So make sure to use "result", not "new".
-                    if isinstance(result, Expression):
-                        result._timestamp_cache(evaluation)
-                    return result, False
+                    new._timestamp_cache(evaluation)
+                    return new, False
                 else:
                     return result, True
 
diff --git a/mathics/eval/numbers/__init__.py b/mathics/eval/numbers/__init__.py
@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """
-Implementation of mathics.builtin.numbers
+Evaluation functions in support of builtin functions under mathics.builtin.numbers
 """
diff --git a/mathics/eval/symbolic_history/__init__.py b/mathics/eval/symbolic_history/__init__.py
@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+Evaluation functions in support of builtin functions under mathics.builtin.symbolic_history
+"""
diff --git a/mathics/eval/symbolic_history/stack.py b/mathics/eval/symbolic_history/stack.py
@@ -0,0 +1,156 @@
+"""
+Evaluation routines from mathics.builtin.symbolic_history.stack
+"""
+
+import inspect
+from typing import Any, Callable, Tuple
+
+import mathics.eval.tracing
+from mathics.core.atoms import Symbol
+from mathics.core.evaluation import Evaluation
+from mathics.core.expression import Expression
+from mathics.core.list import ListExpression
+from mathics.core.symbols import SymbolConstant, SymbolHoldForm
+
+
+def eval_Stack() -> ListExpression:
+    """
+    Display the Python call stack but filtered so that we Builtin calls.
+    """
+
+    frame = inspect.currentframe()
+    assert frame is not None
+    frame = frame.f_back
+    frame_number = -2
+
+    frames = []
+    last_self_obj = None
+    while frame is not None:
+        is_builtin, self_obj = is_showable_frame(frame)
+        if is_builtin:
+            # The two frames are always Stacktrace[]
+            # and Evaluate of that. So skip these.
+            if frame_number > 0:
+                if self_obj != last_self_obj:
+                    if isinstance(self_obj, Expression):
+                        frames.insert(0, Expression(SymbolHoldForm, self_obj))
+                    else:
+                        builtin_class = self_obj.__class__
+                        mathics_builtin_name = builtin_class.__name__
+                        frames.insert(0, Symbol(mathics_builtin_name))
+                    last_self_obj = self_obj
+            frame_number += 1
+        frame = frame.f_back
+
+    return ListExpression(*frames)
+
+
+def save_evaluate(expr, evaluation, status: str, fn: Callable, orig_expr=None):
+    """
+    Called from a decorated Python @trace_evaluate .evaluate()
+    method when Trace["evaluate" -> True]
+    """
+
+    # Test and dispose of various situations where showing information
+    # is pretty useless: evaluating a Symbol is the Symbol.
+    # Showing the return value of a ListExpression literal is
+    # also useless.
+
+    if isinstance(expr, Symbol) and not isinstance(expr, SymbolConstant):
+        return
+
+    if (
+        status == "Returning"
+        and hasattr(expr, "is_literal")
+        and expr.is_literal
+        and hasattr(orig_expr, "is_literal")
+        and orig_expr.is_literal
+    ):
+        return
+
+    if orig_expr == expr:
+        # If the two expressions are the same, there is no point in
+        # repeating the output.
+        return
+
+    # Below, We have to save not only the expression result but also
+    # for returns where the return came from in order to prevent
+    # seeing a return value twice, once form rewite_apply_eval_step,
+    # and once from Expression.evaluate.
+
+    fn_name = fn.__name__
+    if orig_expr is not None:
+        if fn_name == "rewrite_apply_eval_step":
+            assert isinstance(expr, tuple)
+            if orig_expr != expr[0]:
+                evaluation.trace_info.append(
+                    (fn_name, Expression(SymbolHoldForm, expr[0]))
+                )
+        else:
+            evaluation.trace_info.append((fn_name, Expression(SymbolHoldForm, expr)))
+
+    elif fn_name != "rewrite_apply_eval_step":
+        evaluation.trace_info.append((fn_name, Expression(SymbolHoldForm, expr)))
+    return
+
+
+def eval_Trace(expr, evaluation: Evaluation) -> ListExpression:
+    """
+    Display the evaluation calls.
+    """
+
+    evaluation.trace_info = []
+    old_evaluation_call_hook = mathics.eval.tracing.trace_evaluate_on_call
+    old_evaluation_return_hook = mathics.eval.tracing.trace_evaluate_on_return
+
+    mathics.eval.tracing.trace_evaluate_on_call = save_evaluate
+    mathics.eval.tracing.trace_evaluate_on_return = save_evaluate
+
+    try:
+        expr.evaluate(evaluation)
+    except Exception:
+        raise
+    finally:
+        mathics.eval.tracing.trace_evaluate_on_call = old_evaluation_call_hook
+        mathics.eval.tracing.trace_evaluate_on_return = old_evaluation_return_hook
+
+    result = []
+    # We can get duplicate results in returns as a result of
+    # rewrite_eval_step returning and then evaluation returning.
+    # So we filter this case out.
+
+    last_expr = None
+    last_fn_name = ""
+
+    for fn_name, expr in evaluation.trace_info:
+        if (
+            not (last_fn_name == "rewrite_apply_eval_step" and fn_name == "evaluate")
+            or last_expr != expr
+        ):
+            result.append(expr)
+        last_fn_name = fn_name
+        last_expr = expr
+
+    return ListExpression(*result)
+
+
+def is_showable_frame(frame) -> Tuple[bool, Any]:
+    """
+    Return True if frame is the frame for an eval() function of a
+    Mathics3 Builtin function, {List,}Expression.evaluate(),
+    or a rewrite step.
+
+    We make the check based on whether the function name starts with "eval",
+    has a "self" parameter and the class that self is an instance of the Builtin
+    class.
+    """
+    from mathics.core.builtin import Builtin
+    from mathics.core.expression import Expression
+
+    if not inspect.isframe(frame):
+        return False, None
+    if not frame.f_code.co_name.startswith("eval"):
+        return False, None
+    self_obj = frame.f_locals.get("self")
+
+    return isinstance(self_obj, (Builtin, Expression)), self_obj
diff --git a/mathics/eval/trace.py b/mathics/eval/trace.py
diff --git a/test/builtin/symbolic_history/test_stack.py b/test/builtin/symbolic_history/test_stack.py
diff --git a/test/package/test_vectoranalysis.py b/test/package/test_vectoranalysis.py

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# -*- coding: utf-8 -*-
 +"""
 +Evaluation functions in support of builtin functions under mathics.builtin.symbolic_history
 +"""