DOCUMENTATION

XCX REPL and Interactive Execution Shell

The XCX compiler contains an interactive Read-Eval-Print Loop (REPL) engine located in src/repl/. The REPL provides an incremental execution shell that parses, type-checks, JIT-compiles, and runs XCX statements interactively while preserving variables, constants, type states, and string symbols across evaluations.

Interactive Loop Architecture (src/repl/repl.rs)

The entry point of the interactive workspace is the Repl struct:

State Persistence

Unlike a standard file-based compilation pass that discards metadata after emitting assembly or bytecode, the Repl retains the following state to enable incremental interaction:

1. VM Instance (vm: Arc<VM>): Retains globally allocated data, active JIT compilation databases, and environment contexts.

2. Symbol Table (symbols: SymbolTable<'static>): Preserves types, signatures, and addresses of previously declared variables, functions, and fibers.

3. String Interner (interner: Interner): Maintains unique string identifiers (StringId) across statements. Each input evaluation extracts the updated interner state from the parser context.

Execution Loop (Repl::run)

The execution loop manages command input and evaluation cycles:

1. Prompts or reads input via InputReader.

2. Inspects input prefixes. If starting with !, delegates to command handling.

3. If structural code, invokes the compiler pipeline:

• Lexing & Parsing: Initializes Lexer and Parser (transferring the current REPL Interner).
• Semantic Checking: Checks AST nodes using Checker::new(&self.interner) against the persistent SymbolTable.
• Compilation: Compiles AST nodes into a main execution chunk, updating JIT structures and static constants.
• VM Execution: Dispatches the main bytecode chunk to self.vm.run inside a temporary execution context.

Cooperative shutdown is backed by a single consolidated SHUTDOWN flag (set by the Ctrl-C handler); the VM dispatch loop polls it every 1024 executed instructions, so an interrupt stops a running REPL evaluation cleanly instead of being ignored.

Multi-Line Input Editor (src/repl/input.rs)

To support comfortable multi-line coding blocks directly within the interactive shell, the REPL features a raw-mode terminal editor backed by crossterm.

Interactive Features

• Arrow Keys Navigation: Users can freely navigate the cursor up, down, left, and right within their multi-line input block to modify previous lines before executing.
• Line Navigation Shortcuts: Ctrl+A jumps to the beginning of the current interactive line, and Ctrl+E jumps to the end.
• Tab Key Indentation: Pressing Tab automatically inserts exactly 4 spaces (instead of a literal tab character) to maintain readable indent alignment.
• Prompt Transitions: The standard xcx> prompt initiates the primary buffer, while ... prefixes subsequent lines upon pressing Enter.

Executing Code

Input gathering allows developers to arbitrarily draft their scripts across lines. To dispatch the written block of code to the compiler, developers use the interactive !exec command:

1. Press <ENTER> to open a fresh line.

2. Type !exec and press <ENTER>.

The shell captures the entire visual block, parses it, executes the code, and clears the input buffer for the next cycle. Any direct input command starting with ! evaluates immediately.

Interactive Commands

Interactive commands bypass semantic validation and are handled directly in the parser loop:

Module Placeholders

The REPL references structural components with standard constructors; Completer and History remain placeholders for future updates, while Highlighter is fully functional:

• Completer (src/repl/completer.rs): Placeholder setup for tab-autocomplete hooks.
• Highlighter (src/repl/highlighter.rs): Functional syntax highlighter used by the input editor's redraw loop (comments green, strings yellow, types cyan, keywords blue/bold, constants and numbers magenta, REPL ! commands magenta).
• History (src/repl/history.rs): Placeholder setup for persistent interactive command line logs.