Convert to an iterative eval loop instead of a recursive one.

This is a major change in the script evaluation process, which changes
how "special execution" functions work. Previously, functions could
choose to implement execs instead of exec, which received a ParseTree,
instead of Mixed. This allowed the individual function to decide how or
even if the ParseTree nodes were further executed. This works in
general, however it has several drawbacks.

In particular, the core evaluation loop loses control over the script
once it decends into individual functions. Therefore features like
Ctrl+C in command line scripts relied on each of these "flow" functions
to implement that feature correctly, and only some of them did. This
also prevents new features from being implemented as easily, like a debugger,
since the evaluation loop would need to be modified, and every single
flow function would need to make the same changes as well.

This also has several performance benefits. Using a recursive approach
meant that each frame of MethodScript had about 3 Java frames, which is
inefficient. The biggest performance change with this is moving away
from exception based control flow. Previously, return, break, and
continue were all implemented with Java exceptions. This is way more
expensive than it needs to be, especially for very unexecptional cases
such as return(). Now, when a proc or closure returns, it triggers a
different phase in the state machine, instead of throwing an exception.

This also unlocks future features that were not possible today. A
debugger could have been implemented before (though it would have been
difficult) but now an asynchronous debugger can be implemented.
async/await is also possible now. Tail call optimizations can be done,
execution time quotas, and the profiler can probably be improved.

Author: LadyCailin

src/main/java/com/laytonsmith/core/EvalStack.java

@@ -0,0 +1,60 @@
+package com.laytonsmith.core;
+
+import java.util.ArrayDeque;
+import java.util.Iterator;
+
+/**
+ * A wrapper around an {@link ArrayDeque} of {@link StackFrame}s that provides a debugger-friendly
+ * {@link #toString()} showing the current execution stack in the style of MethodScript stack traces.
+ */
+public class EvalStack implements Iterable<StackFrame> {
+
+	private final ArrayDeque<StackFrame> stack;
+
+	public EvalStack() {
+		this.stack = new ArrayDeque<>();
+	}
+
+	public void push(StackFrame frame) {
+		stack.push(frame);
+	}
+
+	public StackFrame pop() {
+		return stack.pop();
+	}
+
+	public StackFrame peek() {
+		return stack.peek();
+	}
+
+	public boolean isEmpty() {
+		return stack.isEmpty();
+	}
+
+	public int size() {
+		return stack.size();
+	}
+
+	@Override
+	public Iterator<StackFrame> iterator() {
+		return stack.iterator();
+	}
+
+	@Override
+	public String toString() {
+		if(stack.isEmpty()) {
+			return "<empty stack>";
+		}
+		StringBuilder sb = new StringBuilder();
+		boolean first = true;
+		Iterator<StackFrame> it = stack.descendingIterator();
+		while(it.hasNext()) {
+			if(!first) {
+				sb.append("\n");
+			}
+			sb.append("at ").append(it.next().toString());
+			first = false;
+		}
+		return sb.toString();
+	}
+}

src/main/java/com/laytonsmith/core/FlowFunction.java

@@ -0,0 +1,92 @@
+package com.laytonsmith.core;
+
+import com.laytonsmith.core.StepAction.StepResult;
+import com.laytonsmith.core.constructs.Target;
+import com.laytonsmith.core.natives.interfaces.Mixed;
+import com.laytonsmith.core.environments.Environment;
+
+/**
+ * Interface for functions that need to control how their children are evaluated.
+ * This replaces the old {@code execs()} mechanism. Instead of a function calling
+ * {@code parent.eval()} recursively, the interpreter loop calls the FlowFunction methods
+ * and the function returns {@link StepAction} values to direct evaluation.
+ *
+ * <p>Functions that don't need special child evaluation (the majority) don't implement
+ * this interface — the interpreter loop evaluates all their children left-to-right,
+ * then calls {@code exec()} with the results.</p>
+ *
+ * <p>Functions that DO need it (if, for, and, try, etc.) implement this interface
+ * and are driven by the interpreter loop via begin/childCompleted/childInterrupted.</p>
+ *
+ * <p>The type parameter {@code S} is the per-call state type. Since function instances
+ * are singletons, per-call mutable state cannot be stored on the function itself.
+ * Instead, methods receive and return state via {@link StepAction.StepResult}.
+ * The interpreter stores this state on the {@link StackFrame} as {@code Object} and
+ * passes it back (with an unchecked cast) on subsequent calls. Functions that need
+ * no per-call state should use {@code Void} and pass {@code null}.</p>
+ */
+public interface FlowFunction<S> {
+
+	/**
+	 * Called when this function frame is first entered. The function should return
+	 * a {@link StepAction.StepResult} containing the first action (typically
+	 * {@link StepAction.Evaluate}) and the initial per-call state.
+	 *
+	 * @param t The code target of the function call
+	 * @param children The unevaluated child parse trees (same as what execs() received)
+	 * @param env The current environment
+	 * @return The first step action paired with initial state
+	 */
+	StepResult<S> begin(Target t, ParseTree[] children, Environment env);
+
+	/**
+	 * Called each time a child evaluation (requested via {@link StepAction.Evaluate})
+	 * completes successfully. The function receives the result and its per-call state,
+	 * and returns the next action paired with updated state.
+	 *
+	 * @param t The code target of the function call
+	 * @param state The per-call state from the previous step
+	 * @param result The result of the child evaluation
+	 * @param env The current environment
+	 * @return The next step action paired with updated state
+	 */
+	StepResult<S> childCompleted(Target t, S state, Mixed result, Environment env);
+
+	/**
+	 * Called when a child evaluation produced a {@link StepAction.FlowControl} action
+	 * that is propagating up the stack. The function can choose to handle it (e.g.,
+	 * a loop handling a break action) or let it propagate by returning {@code null}.
+	 *
+	 * <p>For example, {@code _for}'s implementation handles {@code BreakAction} by completing
+	 * the loop, and handles {@code ContinueAction} by jumping to the increment step.
+	 * {@code _try}'s implementation handles {@code ThrowAction} by switching to the catch branch.</p>
+	 *
+	 * <p>The default implementation returns {@code null}, propagating the action up.</p>
+	 *
+	 * @param t The code target of the function call
+	 * @param state The per-call state from the previous step
+	 * @param action The flow control action propagating through this frame
+	 * @param env The current environment
+	 * @return A {@link StepAction.StepResult} to handle it, or {@code null} to propagate
+	 */
+	default StepResult<S> childInterrupted(Target t, S state, StepAction.FlowControl action, Environment env) {
+		return null;
+	}
+
+	/**
+	 * Called when this function's frame is being removed from the stack, regardless of
+	 * the reason (normal completion, flow control propagation, or exception). This is
+	 * the FlowFunction equivalent of a {@code finally} block — use it to restore
+	 * environment state that was modified in {@code begin()} (e.g., command sender,
+	 * dynamic scripting mode, stack trace elements).
+	 *
+	 * <p>This is called exactly once per frame, after the final action has been determined
+	 * but before the frame is actually popped. The default implementation is a no-op.</p>
+	 *
+	 * @param t The code target of the function call
+	 * @param state The per-call state (may be null if begin() hasn't been called)
+	 * @param env The current environment
+	 */
+	default void cleanup(Target t, S state, Environment env) {
+	}
+}

src/main/java/com/laytonsmith/core/LocalPackages.java

@@ -9,7 +9,6 @@
 import com.laytonsmith.core.exceptions.ConfigCompileException;
 import com.laytonsmith.core.exceptions.ConfigCompileGroupException;
 import com.laytonsmith.core.exceptions.ConfigRuntimeException;
-import com.laytonsmith.core.exceptions.ProgramFlowManipulationException;
 import com.laytonsmith.core.functions.IncludeCache;
 import com.laytonsmith.core.profiler.ProfilePoint;
 
@@ -223,9 +222,6 @@ public void executeMS(Environment env) {
 				if(e.getMessage() != null && !e.getMessage().trim().isEmpty()) {
 					Static.getLogger().log(Level.INFO, e.getMessage());
 				}
-			} catch (ProgramFlowManipulationException e) {
-				ConfigRuntimeException.HandleUncaughtException(ConfigRuntimeException.CreateUncatchableException(
-						"Cannot break program flow in main files.", e.getTarget()), env);
 			}
 		}
 	}

src/main/java/com/laytonsmith/core/Method.java

@@ -9,7 +9,6 @@
 import com.laytonsmith.core.environments.Environment;
 import com.laytonsmith.core.exceptions.CancelCommandException;
 import com.laytonsmith.core.exceptions.ConfigRuntimeException;
-import com.laytonsmith.core.exceptions.ProgramFlowManipulationException;
 import com.laytonsmith.core.natives.interfaces.Mixed;
 import java.util.Arrays;
 
@@ -40,7 +39,7 @@ public Method(Target t, Environment env, CClassType returnType, String name, CCl
 
 	@Override
 	public Mixed executeCallable(Environment env, Target t, Mixed... values)
-			throws ConfigRuntimeException, ProgramFlowManipulationException, CancelCommandException {
+			throws ConfigRuntimeException, CancelCommandException {
 		throw new UnsupportedOperationException("Not supported yet."); //To change body of generated methods, choose Tools | Templates.
 	}
 

src/main/java/com/laytonsmith/core/MethodScriptCompiler.java

@@ -77,6 +77,7 @@
 import java.util.EmptyStackException;
 import java.util.EnumSet;
 import java.util.HashMap;
+import java.util.IdentityHashMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.LinkedList;
@@ -3053,12 +3054,27 @@ public static Mixed execute(String script, File file, boolean inPureMScript, Env
 	 * @return
 	 */
 	public static Mixed execute(ParseTree root, Environment env, MethodScriptComplete done, Script script) {
-		return execute(root, env, done, script, null);
+		Mixed result;
+		if(root == null) {
+			result = CVoid.VOID;
+		} else {
+			if(script == null) {
+				script = new Script(null, null, env.getEnv(GlobalEnv.class).GetLabel(), env.getEnvClasses(),
+						root.getFileOptions(), null);
+			}
+			result = script.eval(root, env);
+		}
+		if(done != null) {
+			done.done(result.val().trim());
+		}
+		return result;
 	}
 
 	/**
 	 * Executes a pre-compiled MethodScript, given the specified Script environment, but also provides a method to set
-	 * the constants in the script.
+	 * the constants in the script. The $variable bindings are resolved by walking the tree and mapping each Variable
+	 * node's identity to its resolved value, then storing the map in the environment. See
+	 * {@link GlobalEnv#SetDollarVarBindings} for details on why identity-based lookup is used.
 	 *
 	 * @param root
 	 * @param env
@@ -3068,53 +3084,23 @@ public static Mixed execute(ParseTree root, Environment env, MethodScriptComplet
 	 * @return
 	 */
 	public static Mixed execute(ParseTree root, Environment env, MethodScriptComplete done, Script script, List<Variable> vars) {
-		if(root == null) {
-			return CVoid.VOID;
-		}
-		if(script == null) {
-			script = new Script(null, null, env.getEnv(GlobalEnv.class).GetLabel(), env.getEnvClasses(),
-					root.getFileOptions(), null);
-		}
-		if(vars != null) {
-			Map<String, Variable> varMap = new HashMap<>();
+		if(root != null && vars != null && !vars.isEmpty()) {
+			Map<String, String> varValues = new HashMap<>();
 			for(Variable v : vars) {
-				varMap.put(v.getVariableName(), v);
+				varValues.put(v.getVariableName(), v.getDefault());
 			}
+			IdentityHashMap<Mixed, String> dollarBindings = new IdentityHashMap<>();
 			for(Mixed tempNode : root.getAllData()) {
 				if(tempNode instanceof Variable variable) {
-					Variable vv = varMap.get(variable.getVariableName());
-					if(vv != null) {
-						variable.setVal(vv.getDefault());
-					} else {
-						//The variable is unset. I'm not quite sure what cases would cause this
-						variable.setVal("");
+					String val = varValues.get(variable.getVariableName());
+					if(val != null) {
+						dollarBindings.put(tempNode, val);
 					}
 				}
 			}
+			env.getEnv(GlobalEnv.class).SetDollarVarBindings(dollarBindings);
 		}
-		StringBuilder b = new StringBuilder();
-		Mixed returnable = null;
-		for(ParseTree gg : root.getChildren()) {
-			Mixed retc = script.eval(gg, env);
-			if(root.numberOfChildren() == 1) {
-				returnable = retc;
-				if(done == null) {
-					// string builder is not needed, so return immediately
-					return returnable;
-				}
-			}
-			String ret = retc.val();
-			if(!ret.trim().isEmpty()) {
-				b.append(ret).append(" ");
-			}
-		}
-		if(done != null) {
-			done.done(b.toString().trim());
-		}
-		if(returnable != null) {
-			return returnable;
-		}
-		return Static.resolveConstruct(b.toString().trim(), Target.UNKNOWN);
+		return execute(root, env, done, script);
 	}
 
 	private static final List<Character> PDF_STACK = Arrays.asList(