From 53a904e0b0bb7ffea5dc38a706dcacf26625068b Mon Sep 17 00:00:00 2001
From: wagesj45 <jordan@jordanwages.com>
Date: Tue, 19 Aug 2025 04:31:53 -0500
Subject: [PATCH] v2: Add public Interpret(string) with soft-error semantics
 and elapsed time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements developer-facing Interpret API that:

- Parses and executes input via generated Scanner/Parser and current interpreter state.
- Returns the numeric result (decimal) and updates NumericValue/StringValue.
- Emits soft errors: never throws; on error sets NumericValue=0 and StringValue to parser error format or exception message.
- Restores LastExecutionTime measurement for the previous interpretation.

This preserves the original nomenclature while aligning to v2’s FunctionValue model.
---
 src/core/InputInterpreter.cs | 41 ++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/core/InputInterpreter.cs b/src/core/InputInterpreter.cs
index 9bcb797..bd409a4 100644
--- a/src/core/InputInterpreter.cs
+++ b/src/core/InputInterpreter.cs
@@ -10,6 +10,7 @@ namespace csmic
 
         private decimal numericValue = 0;
         private string stringValue = string.Empty;
+        private TimeSpan lastExecutionTime = TimeSpan.Zero;
 
         // Variable stores
         private readonly Dictionary<string, decimal> numericVariables;
@@ -47,6 +48,8 @@ namespace csmic
         public decimal NumericValue => numericValue;
         public string StringValue => stringValue;
 
+        public TimeSpan LastExecutionTime => lastExecutionTime;
+
         #endregion
 
         #region Output Plumbing
@@ -128,6 +131,44 @@ namespace csmic
             return parser.Result;
         }
 
+        // Primary developer-facing API: interpret input and return numeric result
+        public decimal Interpret(string input)
+        {
+            DateTime start = DateTime.Now;
+            try
+            {
+                using var ms = new MemoryStream(Encoding.UTF8.GetBytes(input ?? string.Empty));
+                var scanner = new csmic.Interpreter.Scanner(ms);
+                var parser = new csmic.Interpreter.Parser(scanner)
+                {
+                    Interpreter = this
+                };
+                parser.Parse();
+
+                if (parser.errors.count > 0)
+                {
+                    // Soft error: set numeric to 0 and report a parse error message
+                    ProduceOutput(0m, parser.errors.errMsgFormat);
+                }
+                else
+                {
+                    ProduceOutput(parser.Result);
+                }
+            }
+            catch (Exception ex)
+            {
+                // Soft error: never throw, capture message
+                ProduceOutput(0m, ex.Message);
+            }
+            finally
+            {
+                DateTime end = DateTime.Now;
+                lastExecutionTime = end - start;
+            }
+
+            return this.numericValue;
+        }
+
         #endregion
 
         #region Functions