How Trebol is built¶
This guide and the ones after it are for people who want to know how Trebol works inside: to change it, to port it, or to judge whether to trust it. Each guide says what a part does, why it is that way, how it is done, and which other ways there were.
Four layers¶
┌──────────────────────────────────────────────────────────────┐
│ Your app (.trb) view [...], functions, data │
├──────────────────────────────────────────────────────────────┤
│ UI dialect (Trebol) layout: the dialect → a tree of faces │ src/ui
│ styles, validation, events, languages │
├──────────────────────────────────────────────────────────────┤
│ Core (TypeScript) load · mold · binding · evaluator · │ src/core
│ natives · parse · JSON │
├─────────── await, show ↓ ↑ resume, events ────────┤
│ Host (TypeScript) scheduler · DOM · fetch, WebSocket, │ src/host
│ SSE · theme to CSS · console · files │
├──────────────────────────────────────────────────────────────┤
│ Browser or Node │
└──────────────────────────────────────────────────────────────┘
The core is the language and nothing else. It turns text into values (
load), values back into text (mold), binds words, evaluates, and has the natives that need no outside world: series, math, text,parse, JSON. It never imports the DOM,windowor a Node API.The host is everything that touches the world: the task scheduler, the network, the clock, local storage, the console, files, and in the browser the DOM and the theme’s CSS. The same host code runs in Node, which is how
npm run trband the test suite run Trebol without a browser.The UI dialect is written in Trebol, in
src/ui/ui.trb. It reads aview [...]block withparse, applies styles, and gives the host a tree of faces to draw. Validation, events and translations are Trebol code too.Your app is
.trbfiles. A folder with anapp.trband nothing else is a complete app:trebol devmakes up the HTML page it needs.
The core talks to the host in two ways only. A native that has to wait, such as fetch, gives the
evaluator a promise to wait on (see An evaluator that can pause); and the UI calls show to have its faces drawn. The
host talks back by resuming a task that waited, or by starting a new task when an event arrives.
Why this shape¶
The core is meant to outlive TypeScript. Trebol is written in TypeScript so that it runs in a browser
with nothing to install. One day the core may be rewritten in Zig, for a small native desktop runtime or
for speed. Everything that would make that port hard is kept out of src/core, by rules every change
follows:
Rule in the TypeScript core |
Why it helps a port |
|---|---|
No DOM, no |
a Zig core has no browser either |
Values are fixed-shape records tagged by |
they become a tagged union of 16 bytes |
No JavaScript closures stored in values |
Zig has none; state must be explicit data |
Natives return a |
the evaluator without recursion copies over as it is |
Errors are |
no |
Strings are arrays of code points |
the same indexes in UTF-32 |
Promises only at the host boundary |
in Zig: an id of a pending operation the host resolves |
As much as possible written in Trebol |
Trebol code needs no port at all |
The test suites are written in Trebol |
the same suites check both cores |
The UI is written in Trebol because Rebol’s whole idea is dialects. If Trebol could not write its own
UI dialect in itself, with parse and blocks, it would not be much of a Rebol. And every line of
ui.trb is a line that never needs porting.
HTML and CSS are an implementation detail. You describe intent, a form, a main action, a list, and the
host decides how that becomes DOM nodes and styles. This is what lets the same view block be a desktop
form, a phone form, light or dark, and in nine looks, without changing a word of it.
Why this way — and the alternatives¶
Compile Trebol to JavaScript instead of interpreting it. It would be faster, but Rebol code changes itself and builds code at run time (
do,compose,bind), so a compiler would end up shipping an interpreter anyway, and pausing a task in the middle of anything would be much harder.Write the core in Zig or Rust now, compiled to WebAssembly. That would be the final shape sooner, but every call between the DOM and WebAssembly crosses a boundary, strings must be copied both ways, and the development loop is slower. TypeScript first, with rules that keep the port open, gets a working language now and keeps the option.
Write the UI layer in TypeScript. It would be faster to write at the start, and every change to it would then be a change to the host. In Trebol, the dialect is data the language can read, and the UI is a proof that dialects work.
Use a JavaScript UI framework (React, Vue, Svelte) under the dialect. The dialect maps one face to one DOM node and changes only what changed (see From a block to the screen), so a framework would add a second model of the screen to keep in step with the first, and a dependency that changes on its own timetable.
Where things are¶
Path |
What is there |
|---|---|
|
|
|
|
|
|
|
tests in TypeScript, and |
|
the console, |
There is no build step while working on Trebol. Node runs the TypeScript files directly (it strips the types
as it loads them), and trebol dev strips them on the fly for the browser.
The npm package is built once, when it is packed (tools/build.ts), because Node strips no types inside
node_modules:
File |
What it is |
|---|---|
|
the browser runtime in one module, with the UI dialect inside: what a page loads from a CDN |
|
the |
|
|
Using Trebol from JavaScript¶
A program can run Trebol itself. trebol/host starts a runtime and runs source in it; trebol/core has the
values and mold:
import { startHost, runSource } from 'trebol/host';
import { mold } from 'trebol/core';
const host = startHost();
console.log(mold(await runSource(host, 'reduce [1 + 2 * 3 now/year > 2000]'))); // [9 true]
startUi(host) loads the UI dialect into it as well, so layout builds faces without a page. In a page
built with a bundler, import 'trebol/browser' does what the CDN script does: it runs the page’s
text/trebol scripts.