Skip to content

VirtLang v3.2.0

Choose a tag to compare

@dev-kas dev-kas released this 20 May 18:57
· 50 commits to master since this release

VirtLang-Go v3.2.0 Release Notes: Advanced Debugger Engine with Call Stack & Stepping

We are incredibly excited to announce the release of VirtLang-Go v3.2.0! This version introduces a powerful, integrated debugging engine, building upon the foundational metadata and error reporting features of v3.0.0 and v3.1.0. VirtLang-Go now provides sophisticated internal mechanisms for step-through debugging, breakpoint management, and call stack inspection.

This release is a major step towards a full-featured debugging experience, providing the core engine capabilities for host environments (like Xel) to build rich debugger UIs upon.

⚠️ API Change Notice:

  • The signature of the evaluator.Evaluate function has been updated to support debugger integration. Please see the "API Changes (for Go Consumers)" section below for details on how to adapt your code.

Major Features & Enhancements

  • Integrated Debugger Engine (debugger package):

    • State Management: The debugger can be in Running, Paused, or Stepping states.
    • Breakpoint Management: Full API for setting, removing, clearing, and checking breakpoints by file and line number (debugger.BreakpointManager).
    • Execution Control:
      • Continue(): Resumes execution from a paused state.
      • Pause(): Halts execution at the next debuggable statement.
    • Advanced Stepping Capabilities:
      • StepInto(): Steps into function calls.
      • StepOver(): Executes the current line, stepping over function calls (executing them without stopping inside unless a breakpoint is hit).
      • StepOut(): Executes until the current function returns, then pauses.
    • Call Stack Tracking:
      • The debugger now maintains a CallStack (debugger.CallStack), with each debugger.StackFrame containing function/method name, filename, and line number.
      • PushFrame() and PopFrame() methods allow the engine to manage the call stack during function/method invocations.
    • Synchronization: Robust internal use of mutexes and condition variables to manage debugger states and control evaluator execution.
  • AST Interface Enhancement (ast package):

    • The ast.Stmt and ast.Expr interfaces now include a GetSourceMetadata() SourceMetadata method.
    • All concrete AST node types implement this method, providing a standardized way to access the detailed source location (filename, start/end line & column) embedded in v3.1.0.

Core Interpreter Enhancements

  • Evaluator Debugger Integration:
    • The main evaluator.Evaluate function now accepts a *debugger.Debugger instance.
    • At the beginning of evaluating each (debuggable) AST node, the evaluator:
      1. Updates the debugger's CurrentFile and CurrentLine.
      2. Checks if a breakpoint is hit at the current location using debugger.ShouldStop().
      3. If a breakpoint is hit or the debugger is in a stepping state, it pauses execution using debugger.WaitIfPaused(nodeType). This method now intelligently handles different stepping modes (StepInto, StepOver, StepOut) based on call stack depth.
    • The *debugger.Debugger instance is now threaded through all internal evaluation functions.
  • Call Stack Management in Evaluator:
    • evalCallExpr (for function and constructor calls) now correctly pushes a new StackFrame onto the debugger's CallStack upon entry and pops it upon exit.
    • evalProgram pushes a <main> frame for the top-level program execution.

API Changes (for Go Consumers)

  • evaluator.Evaluate Function Signature Change:
    • Old Signature: func Evaluate(astNode ast.Stmt, env *environment.Environment) (*shared.RuntimeValue, *errors.RuntimeError)
    • New Signature: func Evaluate(astNode ast.Stmt, env *environment.Environment, dbgr *debugger.Debugger) (*shared.RuntimeValue, *errors.RuntimeError)
    • Migration Action (if your Go code directly calls evaluator.Evaluate): You must update your calls to pass a third argument for the debugger.
      • If you are not using debugging features in that context, pass nil:
        // Old:
        // result, err := evaluator.Evaluate(myAstNode, myEnv)
        
        // New:
        result, err := evaluator.Evaluate(myAstNode, myEnv, nil)
      • If you are integrating with the debugger, pass your *debugger.Debugger instance.

Testing

  • Added comprehensive unit tests for the new debugger package, covering:
    • Breakpoint manager functionality.
    • Debugger state transitions and control methods (Pause, Continue, StepInto, StepOver, StepOut).
    • Call stack push/pop operations.
    • Correct behavior of WaitIfPaused with different stepping types and call stack depths.
    • Concurrent access patterns to ensure thread safety.
  • Existing evaluator tests have been updated to pass nil for the debugger argument, ensuring they continue to validate core language evaluation.

Known Issues and Limitations

  • While the engine provides robust stepping and call stack logic, the actual user interface for debugging (e.g., displaying variables, call stack, setting breakpoints via commands) is intended to be implemented by a host environment (like Xel).
  • Variable inspection and expression evaluation capabilities during a debug session are to be provided by the host environment, which can leverage the Debugger.Environment and Debugger.CallStack exposed by the engine.

Upgrade Notes

  • This release adds significant new debugging capabilities to the VirtLang-Go engine.
  • Action Required for Go Consumers: Update any direct calls to evaluator.Evaluate to include the new third *debugger.Debugger argument (pass nil if not debugging).
  • This version is otherwise backwards-compatible for VirtLang-Go language users; their scripts will compile and run as before (unless a debugger is explicitly attached and used by a host environment).

Getting Started

Refer to the README.md and the updated DOCS.md for information on how to use the interpreter, its new debugger engine capabilities, or contribute to the project.

Acknowledgements

Huge congratulations and thanks to @dev-kas for the rapid and impressive development of this advanced debugging engine for VirtLang-Go!