██████╗ ██╗ █████╗ ███╗ ██╗ ██████╗
██╔══██╗██║ ██╔══██╗████╗ ██║██╔════╝
██████╔╝██║ ███████║██╔██╗ ██║██║ ███╗
██╔══██╗██║ ██╔══██║██║╚██╗██║██║ ██║
██║ ██║███████╗██║ ██║██║ ╚████║╚██████╔╝
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝
[R, COMPILED TO BYTECODE — JIT-COMPILED, NOT TREE-WALKED]
"GNU R walks the tree. rlang compiles it."
R in Rust — a compiled R runtime, hosted on the
fusevm bytecode VM with a
three-tier Cranelift JIT — the same engine behind zshrs, stryke, awkrs,
elisp, and rubylang.
Read the Docs · Engineering Report · Primitive Reference
Table of Contents
- [0x00] Overview
- [0x01] Install
- [0x02] Usage
- [0x03] Language Features
- [0x04] Command-Line Flags
- [0x05] Architecture
- [0x06] Parity Harness
- [0x07] Status & Roadmap
- [0x08] Documentation
- [0xFF] License
[0x00] OVERVIEW
GNU R evaluates R by walking a parse tree in C. rlang lexes and parses R to an
AST, lowers it to fusevm bytecode, and runs it on a compiled VM with a
Cranelift JIT. rlang carries no VM or JIT of its own. Highlights:
- Compiled, not tree-walked —
for,while,repeat,if,&&and||lower to native fusevm jumps with native integer loop counters, so the tracing JIT sees ordinary loops. - fusevm-hosted — no local
vm.rs/jit.rs; the shared engine behindzshrs,stryke,awkrs,elisp, andrubylang.jit-disk-cachepersists native code across runs. - Everything is a vector — there are no scalars:
1is a double vector of length one, every value carries attributes (names,dim,class), and every operator recycles and propagatesNA. - Copy-on-modify —
y <- x; y[1] <- 9leavesxalone, and complex targets (l$v[2] <- 9,names(x) <- v) compile the way R defines them: rebuild the container, then re-bind it. - Three-valued logic —
NA & FALSEis FALSE andNA | TRUEis TRUE, because the answer is decided regardless of the missing value. - S3 dispatch —
UseMethodwalks the class vector then.default, with implicit classes for the builtin types. - AOP intercepts — a glob-matched before/after/around call-intercept registry, the same design as zshrs's function intercepts.
- Editor-ready — an LSP server over stdio and a REPL on a persistent host, where a function defined at one prompt completes at the next.
- Differential parity — a 48-snippet corpus diffed live against the reference
Rscript, frozen and replayed in CI with no R installed.
[0x01] INSTALL
# run a file, a one-liner, or the REPL
rlang is a standalone Rust crate (an explicit empty [workspace] keeps it
independent of the meta repo). fusevm is pulled from crates.io with the jit,
jit-disk-cache, and aot features. Run the tests with cargo test.
Zsh tab completion
# or: fpath=(/path/to/rlang/completions $fpath) in .zshrc
&&
[0x02] USAGE
if (n < 2) n else +
# [1] 0 1 1 2 3 5 8 13 21 34 55
x <-
# b c
# 2 3
{
n <- 0
{
n <<- n + 1
n
}
}
tick <-
;
# [1] 3
m <-
# [1] 3 4
|> |> # [1] 3 2 1
[0x03] LANGUAGE FEATURES
Implemented and checked against the reference Rscript:
- Vectors & types — logical, integer, double, character, and list vectors
with
NAin every atomic type, recycling, type promotion inc(), and theLinteger-literal suffix. - Attributes —
names,dim,class, and arbitraryattr(), preserved through arithmetic and subsetting. - All four index forms — positive, negative (exclusion), logical (recycled),
and character (by name), plus
[[,$, and 2-D matrix indexingm[i, j]. - Assignment —
<-,=,->,<<-, growing assignment past the end, index/$/[[targets, nested targets, and replacement functions (names(x) <-,dim(x) <-,class(x) <-, user-defined`f<-`). - Functions — defaults that may refer to other arguments,
...forwarding, R's exact/partial/positional argument matching, lexical closures,return(), and function-position lookup that skips non-function bindings. - Control flow —
if/elseas an expression,for,while,repeat,break,next, and short-circuiting&&/||. - Operators — the full precedence ladder from
?Syntax,%%/%/%with the sign of the divisor,%in%, user-defined%op%, and the native pipe|>. - S3 —
class(),inherits(),structure(),UseMethoddispatch with implicit classes and.defaultfallback. - Primitive library — the apply family (
lapply/sapply/Map/Filter/Reduce/do.call), string and regex functions (paste,sprintf,substr,strsplit,grepl,sub,gsub), numeric summaries (sum,mean,median,var,sd,cumsum,diff), sequence and set functions, and matrix helpers. - R's printing —
[n]index prefixes with 80-column wrapping, shared decimal widths, quoted and left-justified character vectors, named-vector column pairs,[i,]/[,j]matrix layout, and$name/[[n]]list sections.
[0x04] COMMAND-LINE FLAGS
| Flag | Effect |
|---|---|
FILE |
Run a .R script. |
-e SRC |
Run a one-liner. |
--repl |
Interactive REPL on a persistent host. |
--lsp |
Language Server Protocol over stdio. |
--build FILE |
AOT-compile the script's bytecode into the on-disk cache. |
--dump-bytecode FILE |
Print the lowered fusevm chunk. |
[0x05] ARCHITECTURE
rlang contains no virtual machine or JIT of its own. The execution path mirrors
how zshrs hosts zsh and rubylang hosts Ruby:
R source → lexer → parser (AST) → lower to fusevm bytecode → fusevm VM + Cranelift JIT
│
RHost heap (vectors, attributes, environments, closures)
| Piece | How |
|---|---|
| fusevm-hosted | No local vm.rs / jit.rs. R lowers to fusevm bytecode and runs on the shared three-tier Cranelift JIT; jit-disk-cache persists native code across runs. |
| Native control flow | Loops and branches lower to native fusevm jumps over native integer counters, so hot loops trace-compile. |
| Vectors on the host heap | Every R value is a Value::Obj handle into the RHost heap, because R has no scalars and any value can carry attributes. |
| Environments by reference | Frames are Rc<RefCell<..>> environments chained to their enclosure — R's lexical scoping, and what lets <<- reach the defining frame. |
| R truthiness | A condition must be a single non-NA logical, so conditions normalize through a TRUTHY op before a native branch. |
| Complex assignment | f(x) <- v compiles to x <- `f<-`(x, v) and x[i] <- v rebuilds and re-binds x, so nested targets unwind through the same two rules. |
[0x06] PARITY HARNESS
Behaviour is checked against the reference Rscript by a differential parity
harness — cargo run --bin parity diffs the snippet corpus
(tests/data/parity_corpus.R) live against the system R, and tests/parity.rs
replays the frozen outputs in CI with no R installed. Nothing is faked as
working: an unimplemented primitive raises could not find function.
The examples/ directory holds runnable programs that double as tests: the
scripts embed stopifnot assertions that abort on any divergence from R, and
tests/examples.rs runs every example through the binary in CI, asserting a
clean exit and stdout matching the frozen reference output
(cargo run --bin parity -- --freeze-examples regenerates it).
[0x07] STATUS & ROADMAP
The standalone Rscript binary, the REPL, the rkyv bytecode cache, the AOP
call-intercept registry, and the LSP server are all in the tree. The parity
corpus and every example match the reference R byte-for-byte.
Arguments are evaluated eagerly rather than as promises, so substitute() /
quote() / non-standard evaluation are not available; tryCatch and the
condition system, data frames, factors, complex numbers, and apply over matrix
margins are not implemented yet. See BUGS.md for the full
known-gaps list.
[0x08] DOCUMENTATION
- Read the Docs — the HUD documentation site.
- Engineering Report — architecture, value model, roadmap, dependency posture.
- Primitive Reference — the primitive library, generated from the language-server corpus.
BUGS.md— the honest known-gaps list.
[0xFF] LICENSE
MIT — free and open source. See LICENSE.