Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 66 additions & 72 deletions content/en/r.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,64 @@
---
title: "R cells"
weight: 27
description: "A ```r block is an R cell: parsed and checked with go-embedded-r's parser, its names in the dependency graph — but not run yet."
description: "A ```r block is an R cell: parsed with go-embedded-r's parser, run on its evaluator in one shared environment, and bounded in memory, steps and time."
tags: [cells, r]
---

A ` ```r ` block is an R cell (go-notebook v0.8.0 and later). R cells are
**parsed and checked, but not run yet**:
[go-embedded-r](https://github.com/go-embedded-r/r), the pure-Go R these
cells are written for, has a complete parser today (its v0.1.0), and its
evaluator is the next milestones (M2 and M3).
A ` ```r ` block is an R cell (parsed since go-notebook v0.8.0, run since
v0.10.0). The R is [go-embedded-r](https://github.com/go-embedded-r/r), a
pure-Go R: go-notebook starts no external `R`. Its parser checks the cell and
its evaluator runs it. Since v0.12.0 every R cell is bounded (see
[Limits](#limits)).

## What works
```r
xs <- c(2.1, 3.4, 1.9, 5.6)
total <- sum(xs)
total / length(xs)
```

## Running

**One environment.** The R cells of a notebook share one global environment,
so a variable assigned in one cell is there in the next, as in an R console.
A cell re-runs only when it or an R cell it reads changes.

**Output.** What a cell prints is its output, as an R console shows it:
`print`, `cat`, and the value of every visible top-level expression. An
invisible value (`x <- 1`, `invisible(x)`) prints nothing. `message()` output
and the cell's warnings go to the standard error, the warnings in R's own form
(`Warning message:` then `In f(x) : text`; `Warning messages:` and a numbered
line each when there are several). An error fails the cell as
`Error in f(x) : text`, after the output written before it, and the cells that
read it do not run. A cell that goes over a limit fails the same way.

A cell shows text only, no figure.

## Limits

A notebook may come from anyone, so each R cell runs with its own bounds:

| Limit | Default | Ends a cell with |
| --- | --- | --- |
| memory | 512 MiB of vectors allocated in total over the cell, garbage included | `Error: memory limit exceeded: more than 536870912 bytes of vectors allocated` |
| steps (calls plus loop iterations) | 50 million | `Error: evaluation step limit reached` |
| time | 30 s | `stopped: the R cell ran longer than 30s, the limit` |

**Parsing.** An R cell is parsed by go-embedded-r's port of R 4.6's grammar,
which gives the same trees and tokens as R 4.6.2 on all of R's own
`src/library` and `tests` (932 files). A syntax error is reported at the
notebook's line and column, with R's own message:
The step count is measured: `for (i in 1:n) s <- s + i` stops at 16,666,666
iterations under 50 million steps, so a simulation of that size runs and an
endless loop ends in seconds. The session and its variables survive a limit.

A program that embeds the kernel can change them with `kernel.Options.R`: a
zero field is the default, and `-1` is no bound. `--timeout` and `--memory`
apply to R cells as to every cell, and they kill the worker, session
included.

## Parsing

An R cell is parsed by go-embedded-r's port of R 4.6's grammar, which gives
the same trees and tokens as R 4.6.2 on all of R's own `src/library` and
`tests` (932 files). A syntax error is reported at the notebook's line and
column, with R's own message:

````markdown
```r
Expand All @@ -36,9 +78,10 @@ The parse is bounded (4 MiB per cell, a nesting depth of 1000, a million
nodes), so a notebook from anyone cannot make it run long or exhaust memory;
a cell over the limits fails with a message saying so.

**Names.** An R cell joins the [rules of cells](cells.md) and the dependency
graph. Its names follow R's scoping at the top level of the environment the
cell runs in:
## Names

An R cell joins the [rules of cells](cells.md) and the dependency graph. Its
names follow R's scoping at the top level of the environment the cell runs in:

| Construct | In the notebook |
| --- | --- |
Expand All @@ -56,64 +99,15 @@ cell runs in:
on every cell before it, and every later cell that reads a name depends on
it, so nothing it may define is missed.

**Across languages.** An R cell's variables are seen by Go, Ruby and Julia
cells, and an R cell sees theirs, as between Ruby and Go (see
[Ruby cells](ruby.md)); a function assigned at the top level stays in R. A
variable named like a Go keyword (`type`) is not seen by Go cells.

## What does not work yet: running

Running an R cell fails, clearly, and the cells that need it say why:

````markdown
```go
n := 10
```

```r
square <- function(v) v^2
total <- sum(square(seq_len(n)))
```

```go
total + 1
```

```go
n * 2
```
````

```console
$ notebook run r.md
── cell 0 (line 4, ran in 11µs)
── cell 1 (line 8, not run)
error: R cells are parsed and checked, but not run yet: execution arrives with go-embedded-r's evaluator (milestones M2 and M3)
── cell 2 (line 13, not run)
error: blocked: it depends on cell 1, an R cell, and R cells are not run yet
── cell 3 (line 17, ran in 24µs)
20
notebook: 2 cell(s) failed
```

(Real transcripts, from go-notebook v0.8.0.)

- an R cell never runs, and `notebook run` exits non-zero;
- every cell that reads what an R cell defines, directly or through other
cells, in any language, is **blocked**, not silently skipped;
- the other cells run as usual.

go-notebook starts no external `R`: the cells will run on go-embedded-r's own
evaluator when it exists. The HTML page shows an R cell's source uncoloured
(go-rouge has no R lexer).
**R variables stay in R.** They are not shared with Go, Ruby, Julia or C cells
in either direction yet: a Go cell that reads an R name finds it undefined,
and an R cell does not see a Go variable.

## In the browser

The [playground](https://go-notebook.github.io/playground/) (v0.9.0 and later)
parses and checks R cells in the same way, in WebAssembly: the + menu and the
cell's language menu offer R, its badge reads **R · not runnable yet**, a
syntax error is shown at its line in R's words, and the cells that read it
are blocked, in the page's neutral style and not as failures.

The playground's R example notebook (`#5-r`) has an R cell, a Go cell blocked
on it and a Go cell that runs alone.
The [playground](https://go-notebook.github.io/playground/) does not run R
cells: its WebAssembly cores do not link the evaluator. It parses and checks
them: the + menu and the cell's language menu offer R, its badge reads
**R · not runnable yet**, a syntax error is shown at its line in R's words,
and the cells that read it are blocked, in the page's neutral style and not as
failures. Run the notebook with `notebook run` to execute its R cells.
Loading