DOCUMENTATION

XCX Compiler Technical Documentation Suite

This directory contains the comprehensive technical architectural specifications and compiler documentation for the XCX language compiler system (v4.4).

Table of Contents

1. Frontend Syntax Module

• Lexer Details: Token scanning, unicode set operations operators, raw strings, and C-style comments validation.
• Parser Loop: Recursive-descent grammar rules, preprocessing expansions, synchronizations.
• AST Architecture: Syntax structures for expressions and statements.

2. Semantic Analyzer Module

• Checker Flow: Semantic analyzer passes, scoping hierarchies, and validation entrypoints.
• Semantic Type Check: Rules for primitive and complex collection constraints.
• Statement Checker: Declarations, blocks, assignments validation.
• Expression Checker: Check methods, lambdas, operators.

3. Compiler Code Gen Module

• Compiler Flow: Opcodes generation, constant and function registries.
• Registers Controller: Allocation mapping limits.
• Statement Emitting: Loops, variables, conditionals emission.
• Expression Emitting: Mathematical calculations, values loading.

4. HIR Pipeline Module

• HIR Overview: High-level IR pipeline entry point, lowering → inlining → codegen stages.
• HIR Core Structures: HirExprKind/HirStmtKind definitions, typed expressions, flat local indices.
• HIR Lowering: AST-to-HIR lowering for functions, statements, and expressions.
• HIR Inlining Pass: Inlining orchestration, substitution mechanism, and inlining decision policy.
• HIR Codegen: HIR-to-bytecode compilation, shared with the AST codegen path.

5. JIT Compilation Engine

• Core JIT Engine: Cranelift integration, the method compilation pipeline, wrapper/inner call conventions, symbol registration helpers.
• JIT Code Gen Context: Cranelift variable setups, pointer-elision static analysis, JIT type tag inferences, and NaN-boxing bit rules.
• JIT Emitters: Low-level machine representations.

6. Virtual Machine Executor

• VM Executor Execution: Interpreter stack layouts, bytecode loops, call-depth limits, and frame dispatch setup.
• VM Code Specs: Bytecode sets overview, relational table checks.
• VM Value Systems: NaN-boxed tags memory representation.
• VM Objects Structures: Maps, sets, arrays, databases, tables, rows, fibers implementations.

7. Runtime Services and Stdlib

• Core Linkage: Native wrapper functions, FFI setup, boxed conversion.
• Runtime Subsystems: Crypto timers, network web routing.
• Runtime Structs: Custom collections methods, relational transactions.

8. Diagnostics Console Engine

• Errors Pipeline: Spans, Severity levels, Visual colorized terminals Reporter output formatting, and comprehensive error code definitions.

9. Interactive Shell Engine

• REPL Workspace: Variable persistence, multi-line delimiters checks, and shell helper commands.