# R — Wiki

The R statistical language on the Wippy runtime. Call R from Lua; get native Lua
values back. No external process, no network. Under the hood: GNU R 4.6.1 compiled
to a single WebAssembly module on wazero.

This wiki is written to be useful to both humans and LLM agents integrating the
module. Every page is plain markdown.

## Contents

- **[Installation](installation.md)** — add/install the module, lock file, private access.
- **[Usage](usage.md)** — the `r.eval`/`r.plot` API, named-variable and `argv`
  argument binding, the filesystem mounts, the wire envelope, and worked Lua
  examples (including an end-to-end regression + plot).
- **[Architecture](architecture.md)** — how Lua → Wippy → wazero → R.wasm fits
  together; the static monolith; EH-based setjmp/longjmp; the warm inline instance.
- **[Performance](performance.md)** — measured overhead vs native R and why it is
  what it is.
- **[Limitations](limitations.md)** — single-thread, frozen in-guest clock, per-call
  cost, no graphics/network.
- **[License](license.md)** — GPL-3.0 + third-party attribution.

## TL;DR for agents

Declare `imports: { r: r:sdk }` on your entry, then:

```lua
local r = require("r")
local res = r.eval("<R code>", ...luaArgs)
-- res = { stdout=string, stderr=string, error=nil|string, result=<native lua> }
-- one string-keyed table binds each key as an R variable:
r.eval("x + y", { x = 1, y = 3 }).result   -- 4
-- any other args are bound (injection-safe) to the R list `argv`:
r.eval("argv[[1]] + argv[[2]]", 3, 4).result   -- 7
-- plots come back as image bytes (png | svg | pdf):
r.plot("plot(1:10)", { width = 800, height = 600, dpi = 96 }).result
```

- `result` is the value of the **last** R expression, decoded: length-1 vectors →
  Lua scalars; longer vectors and lists → Lua tables; named lists → Lua tables keyed
  by name.
- `error` is the R error message, non-nil **iff** R raised an error (`stop(...)`);
  check it before using `result`. `stderr` carries only fd-2 diagnostics
  (warnings/messages); the error message lives in `error` alone.
- Bind data with named bindings or `argv` rather than string-concatenating it into
  `code` — it is both safer and faster.