// RLANG — ENGINEERING REPORT

Summary

GNU R evaluates R by walking a parse tree in C. rlang takes a different path: it lexes and parses R to an AST, lowers that to fusevm bytecode, and runs it on a compiled VM with a Cranelift JIT. Control flow lowers to native VM jumps over native integer counters so the JIT can trace hot loops; R-specific behaviour is served by a thread-local RHost. It joins fusevm alongside zshrs, stryke, awkrs, elisp, and rubylang, and reuses that shared bytecode VM and JIT rather than shipping its own. The binary is Rscript.

The current tree implements the lexer/parser, AST-to-bytecode lowering, the vector heap with attributes (logical, integer, double, character, list, each with NA), recycling and type promotion, copy-on-modify assignment including nested and replacement-function targets, all four index forms plus [[/$/m[i, j], functions with defaults / ... / R's argument matching, lexical closures and <<-, the full ?Syntax operator ladder with user-defined %op% and the native pipe, S3 UseMethod/NextMethod dispatch, the condition system including restarts (tryCatch/try/on.exit/local/withCallingHandlers/withRestarts), 288 primitives, R's printing rules, the standalone Rscript binary and REPL, the rkyv bytecode cache, the --aot native .fvm executable emitter, the inline-Rust FFI bridge (.rust / .Call), a wasm32-unknown-unknown build, an AOP intercept registry, and an LSP server. Behaviour is diffed against the reference Rscript by a 182-snippet differential parity corpus and 8 runnable examples; both are byte-identical to GNU R 4.6.1. Promises and non-standard evaluation, condition calls, data frames, and part of the linear-algebra surface (solve, det, eigen) are not implemented — see Known gaps.

Hosting on fusevm

rlang contains no virtual machine or JIT of its own. The execution path is:

R source  →  lexer  →  parser → AST  →  lower to fusevm bytecode  →  fusevm VM + Cranelift JIT
                                                 │
                                RHost heap (vectors, attributes, environments, closures)

Value model

R has no scalars. 1 is a double vector of length one, and any value may carry an insertion-ordered attribute map (names, dim, class, or anything set with attr()). rlang models this directly: RData is a tagged vector (logical / integer / double / character / list), each element optional so NA exists in every atomic type, and every object lives on the RHost heap. Attributes are an IndexMap because attributes(x) exposes their order.

Arithmetic recycles the shorter operand and propagates NA. Logical operators implement three-valued logic — NA & FALSE is FALSE and NA | TRUE is TRUE, because the answer is decided regardless of the missing value. Type promotion in c() follows R's rank order (logical < integer < double < character).

Assignment is copy-on-modify, not reference mutation: z <- y; z[1] <- 99 rebuilds z's vector and re-binds the name, leaving y untouched. Complex targets reduce to that same rule — f(x) <- v compiles to x <- `f<-`(x, v), so names(x) <- v, dim(x) <- v, class(x) <- v, user-defined `f<-`, and nested targets like l$v[2] <- 9 all unwind through rebuild-then-rebind.

Environments are the one reference-typed thing: frames are Rc<RefCell<EnvData>> chained to their enclosure, which gives R's lexical scoping and is what lets <<- assign in the defining frame rather than the caller's. Truthiness follows R, not C or the shell: a condition must be a single non-NA logical, so conditions normalize through a TRUTHY host op before a native branch.

Dispatch and the primitive library

S3 is the object system that exists here. UseMethod walks the value's class vector, tries each generic.class binding in order, and falls back to generic.default; builtin types get their implicit classes. class(), inherits(), structure(), and unclass() are present. Function-position lookup skips non-function bindings, so a variable named c does not shadow the c() primitive.

builtins::PRIMITIVES registers 133 names: the apply family (lapply, sapply, vapply, Map, Reduce, Filter, do.call), string and regex functions (paste, sprintf, substr, strsplit, grepl, grep, sub, gsub, trimws), numeric summaries (sum, mean, median, var, sd, cumsum, cumprod, diff, range), sequence and set functions (seq, rep, rev, sort, order, unique, union, intersect, setdiff), coercions and predicates, matrix helpers (matrix, dim, nrow, ncol, t), and the inline-Rust FFI bridge (.rust, .Call). The same corpus backs the LSP's completion and hover.

Printing is its own body of work, because R's console output is part of its observable behaviour: [n] index prefixes with 80-column wrapping, shared decimal widths across a vector, quoted and left-justified character vectors, named-vector column pairs, [i,]/[,j] matrix layout, and $name / [[n]] list sections. Parity is measured on that output, so the formatter is held to the same standard as the evaluator.

Verification

Correctness is measured differentially against the reference implementation, not against a self-recorded baseline.

The 182-snippet corpus and all 8 examples are byte-identical to the reference Rscript from GNU R 4.6.1.

Component status

Known gaps

The honest list, mirroring BUGS.md. Nothing here is faked as working: an unimplemented primitive raises could not find function, and parity is measured against the real Rscript rather than a self-recorded baseline.

Dependency posture

Dependencies are kept foundational and durable — the goal is a crate that still builds cleanly years from now. Direct dependencies from Cargo.toml:

Compatibility & longevity

Links

• Docs — index.html
• Primitive reference — reference.html
• Known gaps — BUGS.md
• Source — github.com/MenkeTechnologies/rlang
• Issues — github.com/MenkeTechnologies/rlang/issues
• fusevm — github.com/MenkeTechnologies/fusevm (the shared VM)
• License — MIT (LICENSE)