AddStatement now passes runtime context for custom handlers

YesNt.Interpreter/Runtime/IStatementContext.cs

@@ -0,0 +1,32 @@
+using System.Collections.Generic;
+
+namespace YesNt.Interpreter.Runtime;
+
+/// <summary>
+/// Exposes the script runtime state accessible to custom statement handlers registered
+/// via <see cref="YesNtInterpreter.AddStatement"/>.
+/// </summary>
+public interface IStatementContext
+{
+    /// <summary>Gets the local variable table for the current scope.</summary>
+    Dictionary<string, string> Variables { get; }
+
+    /// <summary>Gets or sets the global variable table shared across all scopes.</summary>
+    Dictionary<string, string> GlobalVariables { get; set; }
+
+    /// <summary>Gets or sets the text of the line currently being processed.
+    /// Inline-substitution handlers (e.g. <c>%read_line</c>) write their result here.</summary>
+    string CurrentLine { get; set; }
+
+    /// <summary>Gets or sets the zero-based index of the next line to execute.
+    /// Set this to implement control-flow jumps inside a custom statement.</summary>
+    int LineNumber { get; set; }
+
+    /// <summary>Terminates execution with the given message.</summary>
+    /// <param name="message">The message written to debug output.</param>
+    /// <param name="isError">
+    /// <see langword="true"/> to signal an error termination;
+    /// <see langword="false"/> for a planned, non-error termination.
+    /// </param>
+    void Exit(string message, bool isError);
+}

YesNt.Interpreter/Runtime/RuntimeInformation.cs

@@ -13,7 +13,7 @@ namespace YesNt.Interpreter.Runtime;
 /// <see cref="RuntimeInformation"/> whose <see cref="ParentRuntimeInformation"/> points back
 /// to the main execution context.
 /// </summary>
-internal sealed class RuntimeInformation
+internal sealed class RuntimeInformation : IStatementContext
 {
     public event Action<string> OnDebugOutput;
 

YesNt.Interpreter/Runtime/YesNtInterpreter.cs

@@ -111,6 +111,20 @@ public class YesNtInterpreter
         PreScanLines();
     }
 
+    /// <summary>
+    /// Registers a custom statement using a pre-built <see cref="StatementAttribute"/>,
+    /// with access to the script's <see cref="IStatementContext"/> (variables, line number, output, etc.).
+    /// </summary>
+    /// <param name="attribute">The attribute describing the keyword, search mode, and priority.</param>
+    /// <param name="handler">
+    /// The delegate invoked when the statement matches. Receives the argument text and the current
+    /// <see cref="IStatementContext"/> for reading/writing script state.
+    /// </param>
+    public void AddStatement(StatementAttribute attribute, Action<string, IStatementContext> handler)
+    {
+        AddStatement(attribute, args => handler(args, runtimeInfo));
+    }
+
     /// <summary>
     /// Registers a simple custom statement with default settings.
     /// </summary>
@@ -123,6 +137,22 @@ public class YesNtInterpreter
         AddStatement(new StatementAttribute(name, searchMode, spaceAround), handler);
     }
 
+    /// <summary>
+    /// Registers a simple custom statement with default settings,
+    /// with access to the script's <see cref="IStatementContext"/> (variables, line number, output, etc.).
+    /// </summary>
+    /// <param name="name">The keyword to match.</param>
+    /// <param name="searchMode">Where in the line the keyword is searched for.</param>
+    /// <param name="spaceAround">Which sides of the keyword must be padded with a space.</param>
+    /// <param name="handler">
+    /// The delegate invoked when the statement matches. Receives the argument text and the current
+    /// <see cref="IStatementContext"/> for reading/writing script state.
+    /// </param>
+    public void AddStatement(string name, SearchMode searchMode, SpaceAround spaceAround, Action<string, IStatementContext> handler)
+    {
+        AddStatement(new StatementAttribute(name, searchMode, spaceAround), handler);
+    }
+
     /// <summary>
     /// Registers a simple custom statement with a specific syntax-highlight color.
     /// </summary>
@@ -136,6 +166,23 @@ public class YesNtInterpreter
         AddStatement(new StatementAttribute(name, searchMode, spaceAround, consoleColor), handler);
     }
 
+    /// <summary>
+    /// Registers a simple custom statement with a specific syntax-highlight color,
+    /// with access to the script's <see cref="IStatementContext"/> (variables, line number, output, etc.).
+    /// </summary>
+    /// <param name="name">The keyword to match.</param>
+    /// <param name="searchMode">Where in the line the keyword is searched for.</param>
+    /// <param name="spaceAround">Which sides of the keyword must be padded with a space.</param>
+    /// <param name="consoleColor">The color used for syntax highlighting.</param>
+    /// <param name="handler">
+    /// The delegate invoked when the statement matches. Receives the argument text and the current
+    /// <see cref="IStatementContext"/> for reading/writing script state.
+    /// </param>
+    public void AddStatement(string name, SearchMode searchMode, SpaceAround spaceAround, ConsoleColor consoleColor, Action<string, IStatementContext> handler)
+    {
+        AddStatement(new StatementAttribute(name, searchMode, spaceAround, consoleColor), handler);
+    }
+
     /// <summary>
     /// Unregisters all handlers matching the specified keyword <paramref name="name"/>.
     /// </summary>