How Irij Works
Design decisions, code structure, and the trade-offs behind each subsystem. Rendered inline from the Irij repo's docs/internals/ directory.
Pipeline
Source → AST → values. The two-back-ends split and what it implies.
Parser
ANTLR4 grammar + indent rewriter. Lexer quirks and reserved-word traps.
AST
Sealed-interface hierarchies for Decl/Stmt/Expr/Pattern. Why records.
Interpreter (deprecated)
Tree-walking eval, environments, effect stack, handler dispatch. Scheduled for removal in v0.7.0; kept as the eval-interp nREPL op during transition.
Bytecode Compiler
ClassEmitter + ASM. Method shape, variable resolution, indirection.
Effects
Threaded vs state-machine lowering. Trampoline + lifted locals.
Tail-Call Optimization
Self-TCO via GOTO + arg rebind. Mutual TCO trade-offs.
Hot Redef
invokedynamic + MutableCallSite. The --direct-linking deploy mode.
Specs
Runtime predicates, contracts, blame tracking.
Modules
mod/use/pub. Inlining, alias rewriting, blame envelopes.
Concurrency
Virtual threads, structured concurrency, cross-mode dispatch.
JVM Capability
Why all Java interop requires ::: JVM.
Stdlib
What lives in Java vs Irij. The Phase 3 port.
nREPL
Protocol, sessions, eval vs eval-bytecode.
Glossary
Terms used throughout these docs.