Interpreter Phase 4: Eval Block Support with die/return/ListNode

[fglock]

Summary

Implement complete eval block support for the interpreter, including exception handling, die/return operators, and high-performance ListNode operations. This enables the interpreter to handle real-world Perl eval blocks with proper error handling.

Changes

1. Eval Block Infrastructure (b3fa767)

• New Opcodes:
  • EVAL_TRY (83): Set up exception handler, clear $@
  • EVAL_CATCH (84): Handle exceptions, store undef
  • EVAL_END (85): Clear $@ on success
• TokenIndex Tracking: Map bytecode PC to AST tokenIndex for error reporting
• Exception Handling: Eval stack to track catch handlers

2. Return and Die Operators (95ec9ae)

• return: Emits RETURN opcode with expression or undef
• die: Emits DIE opcode, calls WarnDie.die() throwing PerlDieException
• warn: Emits WARN opcode for completeness
• Both track tokenIndex for accurate error messages

3. High-Performance ListNode Support (591cdac)

• New Opcode:
  • CREATE_LIST (86): Optimized list creation
    • Fast path for empty lists (count=0)
    • Optimized path for single element (count=1)
    • Efficient bulk add for multiple elements (count>1)
• Array Variables: Support for @_ (register 1)
• Subroutine Calls: Support for -> operator (eval blocks)
• Auto-conversion: RuntimeList to RuntimeArray in CALL_SUB

Performance Optimizations

1. ListNode Fast Paths: Specialized code for common cases
2. Direct Register Operations: No intermediate object allocations
3. Minimal Boxing: Reduce object creation overhead
4. Inline Evaluation: List elements evaluated directly into registers

Architecture

Eval Block Flow:

1. EVAL_TRY pushes catch handler onto stack, clears $@
2. Block executes normally
3. On exception: Catch handler pops stack, sets $@, returns empty list
4. On success: EVAL_END clears $@, pops handler

List Operations:

• ListNode creates RuntimeList with all elements
• CALL_SUB auto-converts RuntimeList to RuntimeArray
• Eval exceptions return empty list (Perl semantics)

Test Results

All InterpreterTest cases pass:

✅ Test 1: my $x = 5 - OK
✅ Test 2: my $x = 10 + 20 - OK
✅ Test 3: eval { die 'error' } - OK (sets $@, returns undef)
✅ Test 4: eval { return 42 } - OK (clears $@, returns value)

Standard Perl test suite also passes:

use Test::More tests => 4;

my $result1 = eval { die "test error" };
is($result1, undef, "eval block returns undef on die");
like($@, qr/test error/, "eval block sets \$@ on die");

my $result2 = eval { return 42 };
is($result2, 42, "eval block returns value on return");
is($@, '', "eval block clears \$@ on success");

Documentation Updates

• Updated BYTECODE_DOCUMENTATION.md with opcodes 83-86
• Added eval block architecture documentation
• Documented performance optimizations

Related Issues

Closes requirements for:

• Eval block exception handling
• die/return operator support
• ListNode operations
• Dynamic code evaluation

Next Steps

With eval blocks working, the interpreter is ready for:

1. Array operations (global arrays beyond @_)
2. Hash operations (%, global hashes)
3. More builtin operators
4. Control flow (last/next/redo beyond eval)

🤖 Generated with Claude Code (claude.ai/code)