VirtLang v4.0.0

VirtLang-Go v4.0.0 Release Notes: Rich Error Objects, Robust Environments, and String Refinements

We are proud to announce the release of VirtLang-Go v4.0.0! This major version introduces significant enhancements to userland error handling, refines core internal data structures for robustness and thread-safety, and improves the representation of string literals for consumers of the engine's token stream.

This release includes several breaking changes aimed at improving the developer experience, API consistency, and language capabilities. Please review the "Breaking Changes & Migration Guide" carefully.

🚀 Major Userland Enhancement

1. Structured Error Objects in try...catch:
   • Benefit: Error handling in VirtLang scripts is now far more powerful and informative.
   • Details: The variable bound in a catch (e) block is no longer a simple string. It is now a VirtLang object with the following properties:
     • e.message: (String) The textual description of the error.
     • e.stack: (Array) An array of stack frame objects, where each frame is an object like { name: string, file: string, line: number }, representing the call stack at the point the error was thrown. This leverages the debugger engine's snapshot capabilities.
   • Impact (Userland Breaking Change): Scripts using try...catch must be updated to access e.message for the error string, and can now programmatically inspect e.stack for detailed diagnostics.
   • Example:

     // Old (v3.x)
     // try { foo() } catch e { print(e) /* e is a string */ }
     
     // New (v4.0.0)
     try {
         foo()
     } catch e {
         print("Error:", e.message)
         print("Stack Trace:")
         for (let frame in e.stack) {
             print(strings.format("  at %s (%s:%v)", frame.name, frame.file, frame.line))
         }
     }
     

⚙️ Core Engine & API Enhancements (Go Consumers)

1. Refined String Token Literals (Lexer):

   • Benefit: Consumers of the token stream (e.g., tools built on VirtLang-Go, or direct Go API users) now receive string content without surrounding delimiters, simplifying processing.
   • Details: The Literal field of lexer.Token for string types (lexer.String) now contains the raw, unescaped string content itself. The surrounding quotes (" or ') are no longer part of the Token.Literal value. (String unescaping itself was introduced in v3.4.0).
   • Impact (Go API Breaking Change): Go code that directly consumes tokens from lexer.Tokenize() and expected string literals to include their original quotes will need to be adjusted.

2. Environment Package Refactoring (environment):

   • Benefit: Improved internal consistency and a step towards thread-safety for environment operations.
   • Details:
     • environment.NewEnvironment() now returns *Environment (a pointer) instead of Environment (a value).
     • All methods on Environment now have *Environment as their receiver type.
     • The internal Environment.Variables map now stores *shared.RuntimeValue (pointers to runtime values).
     • A sync.RWMutex has been added to the Environment struct, and its methods now use this mutex to protect concurrent access to variables and constants.
   • Impact (Go API Breaking Change): Go code directly using the environment package must be updated:
     • Calls to environment.NewEnvironment() will now receive a pointer.
     • Functions or struct fields expecting environment.Environment will need to be changed to *environment.Environment.
     • Direct access to env.Variables will yield *shared.RuntimeValue.

🐛 Bug Fixes & Other Refinements

1. Correct String Concatenation (+ operator):
   • Fixed an issue where string concatenation could incorrectly include quote characters from the internal representation. It now correctly concatenates the actual string content.
2. Improved Internal environment.DeepCopy:
   • The deep copy logic for environments has been updated to correctly handle the new pointer-based storage in Environment.Variables, ensuring true isolation for debugger snapshots.
3. Enhanced helpers.IsTruthy for Strings:
   • Now correctly determines truthiness based on the raw string content (empty string is falsy, non-empty is truthy), consistent with the new string token literal representation.
4. Corrected Member Expression Key Handling:
   • Minor refinements in evalMemberExpr for handling string keys in computed member access, aligning with the raw string content from tokens.

⚠️ Breaking Changes & Migration Guide Summary

1. Userland: try...catch Error Variable:

   • Change: Error variable e in catch(e) is now an object ({message: string, stack: array[]}).
   • Migration: Update catch blocks to use e.message to access the error string and e.stack for stack trace information.

2. Go API: environment.NewEnvironment & Environment Type:

   • Change: environment.NewEnvironment() returns *Environment. Environment methods use *Environment receivers.
   • Migration: Update Go code to use *environment.Environment where environment.Environment (value type) was previously used.

3. Go API: Lexer String Token Literals:

   • Change: lexer.Token.Literal for strings no longer includes outer quotes.
   • Migration: Adjust Go code consuming tokens to work with raw string content.

4. Prerequisite Breaking Changes from v3.4.0 (Assumed):

   • String literals now interpret standard escape sequences (e.g., \n, \t). Literal backslashes need to be \\.
   • The AST constant for "greater than or equal to" is ast.GreaterThanEqual (>=").

Testing

• Existing test suites have been updated to reflect the new string literal representation, environment API, and the structure of caught error objects.
• Tests for string concatenation and other affected evaluator logic have been verified.

Upgrade Notes

• This is a MAJOR version update due to the significant userland and Go API breaking changes.
• All users and Go API consumers are strongly encouraged to upgrade and adapt their code according to the migration guide. These changes lay a foundation for a more robust, predictable, and developer-friendly engine.

Acknowledgements

Continued dedication from @dev-kas has brought VirtLang-Go to this pivotal v4.0.0 release. These core improvements significantly enhance the language engine's capabilities and the experience for both scriptwriters and Go developers integrating with VirtLang-Go!