v4.1.1

VirtLang v4.1.1 Release Notes: Critical Short-Circuiting Fix for Logical Operators

We are issuing a patch release, VirtLang v4.1.1, to address a critical bug in the logical operator implementation introduced in v4.1.0. This update ensures that the && and || operators correctly perform short-circuit evaluation, a fundamental behavior for these operators in modern languages.

🐛 Bug Fixes

Corrected Short-Circuit Evaluation for && and || Operators

• Problem: In v4.1.0, the right-hand side of a logical expression was always evaluated, regardless of the value of the left-hand side. This violated the principle of short-circuiting. For example, in an expression like false && someFunction(), the someFunction() was incorrectly called even though the outcome of the expression was already determined by the false value. This could lead to unexpected side effects and performance degradation.
• Solution: The evaluation logic for logical expressions (evaluator/evalLogicEx.go) has been rewritten to correctly implement short-circuiting. The interpreter now behaves as expected:
  • For && (AND), the right-hand side is only evaluated if the left-hand side is truthy.
  • For || (OR), the right-hand side is only evaluated if the left-hand side is falsy.
• Impact: This fix restores the correct, expected behavior of the language, prevents unintended function calls, and improves performance by avoiding unnecessary evaluations.

⚙️ Other Improvements

• Documentation: The auto-generated API documentation (DOCS.md) has been updated to include the missing entries for the LogicalExpr and LogicalOperator types that were introduced in v4.1.0.
• Code Quality: Minor refactoring was done in the evaluator for better structure, and an error message for unknown logical operators was corrected from "Unknown comparison operator" to "Unknown logical operator."

🧪 Testing

• To ensure the robustness of this fix, new, specific test cases have been added to the evaluator suite.
• These tests use functions with side effects (modifying an array) to rigorously verify that the right-hand side of an expression is not executed when a short-circuit should occur.

⚠️ Upgrade Notes

• This is a critical bug-fix release.
• All users of v4.1.0 are strongly encouraged to upgrade to v4.1.1 immediately to ensure correct program execution.
• Code that unintentionally relied on the buggy, non-short-circuiting behavior will now execute correctly, which may alter program flow to its intended state.

Acknowledgements

Thank you to @dev-kas for quickly identifying and resolving this critical issue.

VirtLang v4.1.0

VirtLang v4.1.0 Release Notes: Comprehensive Logical Operators and Expression Parsing Overhaul

We are thrilled to announce the release of VirtLang v4.1.0! This version introduces a complete suite of logical operators to the language, significantly enhancing its expressiveness for conditional logic. It also includes a major refinement of the expression parsing hierarchy to ensure correct operator precedence and lay a more robust foundation for future language features.

This update makes writing complex boolean logic more intuitive and powerful, bringing VirtLang's capabilities closer to those of modern, mainstream languages.

🚀 Major Features & Enhancements

1. Full Support for Logical Operators

• Benefit: Write more expressive and efficient conditional logic with standard, short-circuiting operators.
• Details: VirtLang now supports a full set of logical operators, each with standard semantics:
  • && (Logical AND): Evaluates to the right-hand side if the left-hand side is truthy, otherwise returns the left-hand side. Short-circuits evaluation.
  • || (Logical OR): Evaluates to the right-hand side if the left-hand side is falsy, otherwise returns the left-hand side. Short-circuits evaluation.
  • ?? (Nil Coalescing): Evaluates to the right-hand side only if the left-hand side is nil, otherwise returns the left-hand side. Perfect for providing default values.
  • ! (Logical NOT): A unary operator that inverts the truthiness of its operand.
• Implementation:
  • A new ast.LogicalExpr node has been added to the Abstract Syntax Tree to represent these operations.
  • The core evaluation logic in evaluator/evalLogicEx.go correctly implements short-circuiting, which avoids unnecessary computations and side effects.
• Example:

  let user = { name: "Alex", permissions: nil };
  
  // && short-circuits because user.active is not present (nil, thus falsy)
  let canEdit = user.active && user.permissions.canWrite; // canEdit is nil
  
  // || returns the first truthy value
  let displayName = user.name || "Guest"; // displayName is "Alex"
  
  // ?? returns the right side only if the left is nil
  let role = user.role ?? "viewer"; // role is "viewer"
  
  // ! inverts the truthiness
  if (!canEdit) {
      print("User cannot edit the document.");
  }
  

⚙️ Core Interpreter & API Enhancements

1. Expression Parsing Overhaul:
   • Benefit: Establishes a standard and robust operator precedence hierarchy, improving parser predictability and maintainability.
   • Details: The parser's expression handling has been refactored. We've introduced new parsing functions (parseLogicalExpr, parseUnaryExpr) and re-ordered the parsing chain to correctly handle operator precedence. The new order is: Assignment → Logical → Comparison → Additive → Multiplicative → Unary → Call/Member → Primary. This ensures that expressions like !true || false && 1 > 0 are parsed correctly according to standard language rules.
2. Lexer Enhancements:
   • The lexer now recognizes &&, ||, ??, and ! as a new LogicalOperator token type.
   • A new helper function, lexer.IsLogicalOperator, has been added for efficient token identification.
3. Documentation Cleanup:
   • The auto-generated API documentation in DOCS.md has been updated to include all new types and functions.
   • For improved readability, we have removed direct source code links from the headers in DOCS.md.

🧪 Testing

• This release includes a highly comprehensive test suite for the new logical operators.
• Over 30 new test cases have been added to evaluator/evaluator_test.go, covering:
  • Short-circuiting behavior for && and ||.
  • Correct nil-checking for ??.
  • Type coercion and truthiness rules across all value types.
  • Complex expressions involving multiple operators to validate precedence.
  • Verification of De Morgan's laws (e.g., !(A || B) is equivalent to !A && !B).

⚠️ Breaking Changes & Migration Guide

• There are no breaking changes in this release.
• This version is fully backward-compatible. All existing VirtLang scripts will run without modification.

Upgrade Notes

• This is a minor version update that adds significant new functionality.
• Upgrading is highly recommended for all users to take advantage of the new logical operators and the more robust expression parser.

Acknowledgements

A huge thank you to @dev-kas for implementing this foundational feature set, which greatly enhances the power and expressiveness of the VirtLang language

v4.0.1

Full Changelog: v4.0.0...v4.0.1

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!

VirtLang v3.4.0

VirtLang v3.4.0 Release Notes: Enhanced String Literal Processing with Escape Sequence Support

We are pleased to announce the release of VirtLang v3.4.0! This version significantly enhances the capabilities of string literals within the VirtLang language by introducing comprehensive support for escape sequences.

This much-anticipated update allows developers to embed special characters like newlines, tabs, carriage returns, and even Unicode characters directly within their string literals, making string manipulation more intuitive and powerful.

Major Features & Enhancements

1. Full Escape Sequence Support in String Literals (Lexer):

   • Benefit: Developers can now define strings containing special characters (e.g., newlines, tabs, quotes) using standard escape sequences, leading to more readable and expressive code.

   • Details: The VirtLang-Go lexer has been upgraded to correctly parse and unescape the following sequences within string literals (both single-quoted '...' and double-quoted "..."):

     • \n: Newline
     • \t: Tab
     • \r: Carriage Return
     • \b: Backspace (Note: actual behavior in output might depend on terminal/display)
     • \f: Form Feed (Note: actual behavior in output might depend on terminal/display)
     • \\: Backslash
     • \": Double Quote (within a double-quoted string)
     • \': Single Quote (within a single-quoted string)
     • \uXXXX: Unicode character specified by 4 hexadecimal digits (e.g., "\u2388" for Helm symbol Helm symbol).
     • (Note: Octal escapes like \033 are not currently part of this update but may be considered in the future.)

   • Implementation:

     • A new internal helper function lexer.UnescapeString(s string) has been introduced, utilizing strconv.Unquote for robust unescaping.
     • The lexer's string tokenization logic now correctly identifies and processes these escape sequences, ensuring the Token.Literal for string tokens contains the actual unescaped characters (while still being wrapped in its original quotes for consistency if it was originally quoted).
     • Multi-line strings are also correctly handled, with escape sequences processed per line before rejoining.

   • Example:

     let greeting = "Hello,\n\tWorld! \"Welcome\" to VirtLang \u2728.";
     // The 'greeting' variable will now actually contain a newline, a tab,
     // an embedded double quote, and the sparkles Unicode character.
     
     let singleQuotes = 'It\'s a \u263A day!'; 
     // 'singleQuotes' will contain an embedded single quote and a smiley face.
     

Core Lexer Enhancements

• String Tokenization Logic (lexer/lexer.go):
  • The loop for consuming string content now correctly handles escaped quote characters (\", \') to prevent premature termination of the string token.
  • After collecting the raw string content (between the opening and closing quotes), it now processes this content line-by-line (handling \r\n and \r as \n), unescaping each line using the new UnescapeString helper before constructing the final token literal. This ensures correct unescaping even in multi-line raw strings.
  • Improved error reporting for invalid escape sequences within strings, leveraging errors from strconv.Unquote.

Testing

• New Lexer Tests (lexer/lexer_test.go):
  • Added a dedicated test suite TestUnescapeString to validate the behavior of the new lexer.UnescapeString helper function with various inputs, including simple strings, direct unquotes, multiple escape sequences, empty strings, and invalid sequences.
  • Expanded TestTokenize with new test cases specifically covering:
    • Basic escape sequences (\n, \t, \r).
    • Strings with multiple mixed escape sequences.
    • Strings containing all supported escape sequences (\n, \t, \r, \b, \f, \\, \", \').
    • Unicode escape sequences (\uXXXX).
    • Previously problematic cases like strings containing literal newlines (CRLF) are now also correctly tokenized with their content unescaped (newlines preserved).

Known Issues and Limitations

• Octal Escapes: Standard octal escape sequences (e.g., \033) are not currently supported.
• Backspace/Formfeed Display: The actual rendering of \b (backspace) and \f (form feed) is terminal/environment dependent and might not always produce a visible effect as expected in all output contexts.

Upgrade Notes

• This release significantly changes how string literals are processed by the lexer.
• Potential Behavior Change: If your existing VirtLang-Go code contained string literals with character sequences that happen to look like escape sequences (e.g., a literal \ followed by an n like "\\n") but were intended to be literal backslashes and 'n's, these will now be interpreted as actual newline characters.
  • To represent a literal backslash, you must now use \\. For example, to get the string \n, you would write "\\n".
• It is highly recommended to review any string literals in your existing code that use backslashes to ensure they behave as intended with the new unescaping logic.
• This change makes VirtLang-Go strings more aligned with conventions in many other programming languages.

Getting Started

• Update to VirtLang-Go v3.4.0.
• You can now freely use standard escape sequences in your string literals.

Acknowledgements

A significant thank you to @dev-kas for implementing this crucial enhancement to string handling in VirtLang-Go, greatly improving its expressiveness and usability!

v3.3.7

VirtLang v3.3.7

v3.3.6

Full Changelog: v3.3.5...v3.3.6

v3.3.5

Full Changelog: v3.3.4...v3.3.5

v3.3.4

Full Changelog: v3.3.3...v3.3.4

v3.3.3

Full Changelog: v3.3.2...v3.3.3