Joseph Ferano
3e181b52b2
A consistency sweep, run by checking claims against the compiler rather
than reading for style. Every edit here corrects something that is false
now, or adds something the page had no way to say.
`web/index.html` was the worst of it, and the worst of that was control
flow: the page said there is no `loop`/`recur` and no `break` or
`continue`, and printed the refusal message for `break` as evidence. All
four are built, with loop labels. A live code example called
`index-of-i32`, which no longer exists and would not compile. The prelude
table was the pre-generics per-type families, a paragraph said there is
no `println` two paragraphs after calling `println` the compiler's, and
`sqrt-f32` was "the one `declare` in the file" when there are five. The
"Not implemented yet" table listed `Vec`, `Map`, `Handle`, `Fn`, `fn`,
unions, `defmacro` and quasiquote, all of which check; what is actually
left is `Result`, `try`, a quoted symbol as a value, `errdefer`, `await`,
`handler-case` and the restart-stack readers. Restarts take parameters
(`(invoke-restart 'use-value 21)` answers 42), `defer` in a `let` is
allowed, and there is both an allocator and a `context`.
Generics is a new section, because nobody had documented the syntax. The
brief for it was wrong in one place and the corpus settled it: `$t` goes
in *every* type position including the return type, and bare `t` is the
type-name argument in expression position — `(vec-new t)`, `(t x)`. It
says what a type variable is move-only by default means, since that is
the rule a reader hits first and it is not Odin's.
`FLAN_RAYLIB_H` is gone from every doc that claimed it still decided
something. The passages that say "this used to be opt-in" are kept and
labelled; the ones that said "this is opt-in" are not. `plan.org` had
`{string i32}` in the type list and four predicates where there are five.
`conditions.org` described `errdefer`'s behaviour without saying it is
refused by name. `REFERENCES.md` pointed at the gitignored copy of the
raylib header rather than the committed one, which is the exact trap that
made committing it necessary.
Found and not fixed, because it is not documentation: `vendor/raylib/headers`
still says a build reads it "when the variable happens to be set", which
contradicts the section below it in the same file and is false — moving
the header makes every build fail by name.
2033 lines
96 KiB
HTML
2033 lines
96 KiB
HTML
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>Flan</title>
|
||
<meta name="description" content="Flan — a statically typed, GC-free Lisp for game development.">
|
||
<style>
|
||
:root {
|
||
--bg: #fdf8ee;
|
||
--panel: #f6ecd8;
|
||
--code-bg: #fbf3e2;
|
||
--rule: #e4d5b8;
|
||
--text: #3a2a18;
|
||
--muted: #7b6444;
|
||
--accent: #b07a12;
|
||
--link: #96601a;
|
||
|
||
--c-comment: #93795a;
|
||
--c-string: #6d7f3a;
|
||
--c-form: #a8621a;
|
||
--c-num: #8a5a2b;
|
||
--c-type: #4d7684;
|
||
--c-kw: #96604a;
|
||
}
|
||
@media (prefers-color-scheme: dark) {
|
||
:root:not([data-theme="light"]) {
|
||
--bg: #1b1611;
|
||
--panel: #261f18;
|
||
--code-bg: #231d17;
|
||
--rule: #3b3229;
|
||
--text: #efe3cd;
|
||
--muted: #b09c7e;
|
||
--accent: #e0b15e;
|
||
--link: #e0b15e;
|
||
|
||
--c-comment: #8b7c62;
|
||
--c-string: #adc06b;
|
||
--c-form: #e0b15e;
|
||
--c-num: #d9a465;
|
||
--c-type: #8bb6c6;
|
||
--c-kw: #d79c86;
|
||
}
|
||
}
|
||
:root[data-theme="dark"] {
|
||
--bg: #1b1611;
|
||
--panel: #261f18;
|
||
--code-bg: #231d17;
|
||
--rule: #3b3229;
|
||
--text: #efe3cd;
|
||
--muted: #b09c7e;
|
||
--accent: #e0b15e;
|
||
--link: #e0b15e;
|
||
|
||
--c-comment: #8b7c62;
|
||
--c-string: #adc06b;
|
||
--c-form: #e0b15e;
|
||
--c-num: #d9a465;
|
||
--c-type: #8bb6c6;
|
||
--c-kw: #d79c86;
|
||
}
|
||
|
||
html { -webkit-text-size-adjust: 100%; }
|
||
body {
|
||
margin: 0;
|
||
background: var(--bg);
|
||
color: var(--text);
|
||
font: 17px/1.65 "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
|
||
}
|
||
main { display: block; }
|
||
.wrap { max-width: 44rem; margin: 0 auto; padding: 0 1.25rem 6rem; }
|
||
|
||
header { padding: 3.5rem 0 2rem; }
|
||
.mark { display: block; height: 2.6rem; width: auto; }
|
||
.tagline { color: var(--muted); font-size: 1.05rem; margin: .9rem 0 0; }
|
||
|
||
h2 {
|
||
font-size: 1.45rem; line-height: 1.25; font-weight: 600;
|
||
margin: 3.2rem 0 .8rem; padding-top: 1.6rem;
|
||
border-top: 1px solid var(--rule);
|
||
}
|
||
h3 { font-size: 1.08rem; font-weight: 600; margin: 2rem 0 .5rem; }
|
||
h2:target, h3:target { color: var(--accent); }
|
||
p, ul, ol, table { margin: 0 0 1rem; }
|
||
ul, ol { padding-left: 1.3rem; }
|
||
li { margin: .25rem 0; }
|
||
a { color: var(--link); text-decoration-thickness: 1px; text-underline-offset: 2px; }
|
||
|
||
code, pre, kbd {
|
||
font-family: ui-monospace, "SFMono-Regular", "Cascadia Mono", Menlo, Consolas, monospace;
|
||
font-size: .875em;
|
||
}
|
||
p code, li code, td code, h3 code {
|
||
background: var(--panel);
|
||
border-radius: 3px;
|
||
padding: .1em .32em;
|
||
}
|
||
kbd {
|
||
background: var(--panel); border: 1px solid var(--rule);
|
||
border-radius: 3px; padding: .05em .35em; white-space: nowrap;
|
||
}
|
||
pre {
|
||
background: var(--code-bg);
|
||
border: 1px solid var(--rule);
|
||
border-left: 3px solid var(--accent);
|
||
border-radius: 4px;
|
||
padding: .85rem 1rem;
|
||
overflow-x: auto;
|
||
line-height: 1.55;
|
||
margin: 0 0 1.15rem;
|
||
}
|
||
pre code { background: none; padding: 0; font-size: .8125rem; }
|
||
|
||
table { border-collapse: collapse; width: 100%; font-size: .94rem; }
|
||
th, td { text-align: left; padding: .38rem .6rem .38rem 0; border-bottom: 1px solid var(--rule); vertical-align: top; }
|
||
th { font-weight: 600; color: var(--muted); }
|
||
.scroll { overflow-x: auto; margin: 0 0 1.15rem; }
|
||
|
||
/* Tabs. The panels are visible by default and only become switchable once
|
||
the script adds .tabbed to <main> — with no script the page is the one long
|
||
document it has always been, which is also what a printer and a text browser
|
||
get. */
|
||
.tabs {
|
||
display: flex; flex-wrap: wrap; gap: .4rem;
|
||
margin: 0 0 2rem; padding: 0 0 .6rem;
|
||
border-bottom: 1px solid var(--rule);
|
||
}
|
||
.tabs button {
|
||
font: inherit; font-size: .93rem; cursor: pointer;
|
||
background: none; border: 1px solid transparent; border-radius: 4px;
|
||
padding: .3rem .7rem; color: var(--muted);
|
||
}
|
||
.tabs button:hover { color: var(--link); }
|
||
.tabs button[aria-selected="true"] {
|
||
color: var(--text); background: var(--panel); border-color: var(--rule);
|
||
}
|
||
.tabs button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
||
main:not(.tabbed) .tabs { display: none; }
|
||
main.tabbed .panel[hidden] { display: none; }
|
||
|
||
.toc-group {
|
||
margin: 1.1rem 0 .3rem; font-size: .72rem; letter-spacing: .09em;
|
||
text-transform: uppercase; color: var(--muted); opacity: .75;
|
||
}
|
||
.toc-group:first-child { margin-top: 0; }
|
||
|
||
.lede { font-size: 1.1rem; }
|
||
.note { color: var(--muted); font-size: .94rem; }
|
||
|
||
/* The table of contents: a bar with a toggle when the window is narrow, a
|
||
fixed column beside the text when there is room for one. The toggle is a
|
||
checkbox so that no script is needed to open it. */
|
||
.toc-toggle { position: absolute; width: 1px; height: 1px; opacity: 0; }
|
||
.toc-button {
|
||
display: block; cursor: pointer; user-select: none;
|
||
position: sticky; top: 0; z-index: 2;
|
||
padding: .6rem 1.25rem;
|
||
background: var(--panel); border-bottom: 1px solid var(--rule);
|
||
color: var(--muted); font-size: .92rem; letter-spacing: .02em;
|
||
}
|
||
.toc-button::before { content: "\2261\00a0\00a0"; }
|
||
.toc-toggle:focus-visible + .toc-button { outline: 2px solid var(--accent); outline-offset: -2px; }
|
||
nav.toc {
|
||
display: none;
|
||
background: var(--panel); border-bottom: 1px solid var(--rule);
|
||
padding: .75rem 1.25rem 1.1rem;
|
||
}
|
||
.toc-toggle:checked ~ nav.toc { display: block; }
|
||
.toc-title {
|
||
display: none; /* the toggle already says "Contents" */
|
||
margin: 0 0 .5rem; font-size: .78rem; letter-spacing: .09em;
|
||
text-transform: uppercase; color: var(--muted);
|
||
}
|
||
nav.toc ul { list-style: none; padding: 0; margin: 0; }
|
||
nav.toc li { margin: 0; font-size: .93rem; }
|
||
nav.toc a {
|
||
display: block; padding: .2rem 0; color: var(--muted);
|
||
text-decoration: none; border-left: 2px solid transparent; padding-left: .6rem;
|
||
}
|
||
nav.toc a:hover { color: var(--link); border-left-color: var(--accent); }
|
||
h2, h3 { scroll-margin-top: 3.5rem; }
|
||
|
||
/* Nineteen entries one to a line fills a phone screen, so the opened panel
|
||
goes to two columns as soon as there is room for them. */
|
||
@media (min-width: 30rem) and (max-width: 65.99rem) {
|
||
nav.toc ul { columns: 2; column-gap: 1.5rem; }
|
||
nav.toc li { break-inside: avoid; }
|
||
}
|
||
footer { margin-top: 3.5rem; padding-top: 1.5rem; border-top: 1px solid var(--rule); color: var(--muted); font-size: .92rem; }
|
||
|
||
/* Wide enough for both: the contents become a column of their own, scrolling
|
||
independently of the page, and the text moves over to sit beside it. */
|
||
@media (min-width: 66rem) {
|
||
.toc-button { display: none; }
|
||
nav.toc {
|
||
display: block;
|
||
position: fixed; top: 0; left: 0; bottom: 0;
|
||
width: 15rem; overflow-y: auto; overscroll-behavior: contain;
|
||
background: none; border-bottom: 0; border-right: 1px solid var(--rule);
|
||
padding: 3.6rem 1rem 2rem 1.5rem;
|
||
}
|
||
main { margin-left: 15rem; }
|
||
.toc-title { display: block; }
|
||
h2, h3 { scroll-margin-top: 1rem; }
|
||
}
|
||
|
||
.c { color: var(--c-comment); font-style: italic; }
|
||
.s { color: var(--c-string); }
|
||
.f { color: var(--c-form); font-weight: 600; }
|
||
.n { color: var(--c-num); }
|
||
.t { color: var(--c-type); }
|
||
.k { color: var(--c-kw); }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<input type="checkbox" id="toc-toggle" class="toc-toggle">
|
||
<label class="toc-button" for="toc-toggle">Contents</label>
|
||
|
||
<nav class="toc" aria-label="Contents">
|
||
<p class="toc-title">Contents</p>
|
||
<p class="toc-group">Language</p>
|
||
<ul>
|
||
<li><a href="#what">What Flan is</a></li>
|
||
<li><a href="#start">Getting started</a></li>
|
||
<li><a href="#values">Values and memory</a></li>
|
||
<li><a href="#types">Types</a></li>
|
||
<li><a href="#structs">Structs and enums</a></li>
|
||
<li><a href="#functions">Functions</a></li>
|
||
<li><a href="#control">Control flow</a></li>
|
||
<li><a href="#defer">defer</a></li>
|
||
<li><a href="#arrays">Arrays and slices</a></li>
|
||
<li><a href="#generics">Generics</a></li>
|
||
<li><a href="#printing">Printing</a></li>
|
||
<li><a href="#prelude">The prelude</a></li>
|
||
<li><a href="#packages">Packages</a></li>
|
||
</ul>
|
||
<p class="toc-group">Conditions</p>
|
||
<ul>
|
||
<li><a href="#conditions">Conditions and restarts</a></li>
|
||
<li><a href="#break">The break loop</a></li>
|
||
</ul>
|
||
<p class="toc-group">The FFI</p>
|
||
<ul>
|
||
<li><a href="#ffi">The FFI</a></li>
|
||
</ul>
|
||
<p class="toc-group">The dev loop</p>
|
||
<ul>
|
||
<li><a href="#devloop">The dev loop</a></li>
|
||
<li><a href="#emacs">Emacs</a></li>
|
||
</ul>
|
||
<p class="toc-group">Builds</p>
|
||
<ul>
|
||
<li><a href="#targets">Targets and builds</a></li>
|
||
<li><a href="#notyet">Not implemented yet</a></li>
|
||
<li><a href="#reading">Further reading</a></li>
|
||
</ul>
|
||
</nav>
|
||
|
||
<main>
|
||
<div class="wrap">
|
||
|
||
<div class="tabs" role="tablist" aria-label="Sections">
|
||
<button type="button" role="tab" data-panel="panel-language" aria-selected="true">Language</button>
|
||
<button type="button" role="tab" data-panel="panel-conditions" aria-selected="false">Conditions</button>
|
||
<button type="button" role="tab" data-panel="panel-ffi" aria-selected="false">The FFI</button>
|
||
<button type="button" role="tab" data-panel="panel-devloop" aria-selected="false">The dev loop</button>
|
||
<button type="button" role="tab" data-panel="panel-builds" aria-selected="false">Builds</button>
|
||
</div>
|
||
|
||
<header>
|
||
<svg class="mark" viewBox="0 0 118 44" role="img" aria-label="Flan">
|
||
<!-- The dot is a full stop in the same run, so it stays beside the n
|
||
whichever serif the reader actually has. -->
|
||
<text x="0" y="33" font-family="Iowan Old Style, Palatino, Georgia, serif"
|
||
font-size="38" font-weight="600" letter-spacing="1"
|
||
fill="currentColor">flan<tspan fill="var(--accent)">.</tspan></text>
|
||
</svg>
|
||
<p class="tagline">A statically typed Lisp for game development. Clojure's brackets,
|
||
C's memory and value model, no garbage collector.</p>
|
||
</header>
|
||
|
||
<p class="lede">Flan compiles s-expressions to LLVM IR and then to a native binary.
|
||
There are no object headers, so a Flan struct is exactly its C struct. There is no
|
||
collector, so nothing runs between frames that you did not write. And a running
|
||
program can be edited: a function recompiled in Emacs is installed into the live
|
||
process at its next frame boundary, in about twenty milliseconds.</p>
|
||
|
||
<p>This page describes the compiler <em>as it is</em>, not as it is planned. Where
|
||
something is designed but not built, it says so and gives the message the compiler
|
||
prints for it. Every Flan program on this page is a file in <code>web/examples/</code>
|
||
with its output recorded beside it; <code>sh web/examples/check.sh</code> runs them all
|
||
and compares, and <code>quotes.sh</code> re-derives the blocks that are transcripts
|
||
rather than programs.</p>
|
||
|
||
<div class="panel" id="panel-language">
|
||
|
||
<h2 id="what">What Flan is</h2>
|
||
|
||
<p>A minimal Lisp for games. In one line: Odin with a Lisp frontend and a live REPL.
|
||
Types are mandatory and inference makes them feel optional; memory is manual; the
|
||
frontend is OCaml, and the default backend writes LLVM IR as text and hands it to
|
||
<code>clang</code>. There is a second one, off by default, that emits x86-64 by hand —
|
||
see <a href="#targets">targets and builds</a>.</p>
|
||
|
||
<p>What it is not:</p>
|
||
|
||
<ul>
|
||
<li><strong>Not a Common Lisp and not a Clojure.</strong> No numeric tower, no CLOS,
|
||
no <code>format</code>, no lazy seqs, no persistent collections, no JVM.</li>
|
||
<li><strong>No immutable collection types.</strong> Structure sharing destroys clear
|
||
ownership, and clear ownership is the only thing that removes the need for a
|
||
collector. Value structs that copy on assignment replace them.</li>
|
||
<li><strong>No dynamic typing.</strong> A tag word on every value is exactly the
|
||
header cost that dropping the GC was meant to avoid.</li>
|
||
<li><strong>No consoles</strong>, and no live-image development at SBCL's level.</li>
|
||
</ul>
|
||
|
||
<h2 id="start">Getting started</h2>
|
||
|
||
<p>You need OCaml with dune, and a <code>clang</code> on <code>PATH</code>. Build the
|
||
compiler, then run something:</p>
|
||
|
||
<pre><code class="sh">$ dune build
|
||
$ ./_build/default/bin/main.exe run calc-me.flan "1 + 2 * (3 - 0.5) / 2"
|
||
3.5</code></pre>
|
||
|
||
<p>Call that binary <code>flan</code>. Its subcommands:</p>
|
||
|
||
<pre><code class="sh">$ flan
|
||
usage: flan (read|parse|check|emit|shim) <file.flan>...
|
||
flan import-c <header.h> [package.flan...] [clang flags...]
|
||
flan generate-c <package-dir>
|
||
flan build <file.flan> [-o out] [--no-bounds-checks] [--dev] [--debug] [--sanitize] [--x86] [--target=wasm32-wasi|web]
|
||
flan run <file.flan> [args...]
|
||
flan reload <program.flan> <forms.flan> [-o out.so]
|
||
flan dev <program.flan> [-s socket]</code></pre>
|
||
|
||
<p><code>read</code>, <code>parse</code>, <code>check</code>, <code>emit</code> and
|
||
<code>shim</code> each stop the pipeline one stage further along and print what it
|
||
produced. <code>run</code> builds to a temporary file and execs it.</p>
|
||
|
||
<p>The smallest program:</p>
|
||
|
||
<pre><code>(defn main [] ()
|
||
(println "hello from flan"))</code></pre>
|
||
|
||
<p>The entry point is <code>(defn main [args [string]] i32)</code>. The parameter is
|
||
optional — omitting <code>args</code> means the program ignores argv — and the return
|
||
type is not: <code>()</code> is unit, and a <code>main</code> that returns it exits 0.</p>
|
||
|
||
<h2 id="values">Values and memory</h2>
|
||
|
||
<p>There is no garbage collector and no hidden allocation. Every local is a stack
|
||
slot; reading one is a load, assigning to one is a store, and a store of an aggregate
|
||
<em>is</em> the copy. A struct is its C layout with nothing added.</p>
|
||
|
||
<p>Four rules carry most of the model:</p>
|
||
|
||
<ul>
|
||
<li><strong>Zero is initialisation.</strong> A declaration with no initialiser is
|
||
all-bytes-zero, so a global array is BSS and costs nothing to start. A struct
|
||
literal that omits a field zeroes it. <code>(zeroed)</code> re-zeroes something
|
||
later — a memset, not an allocation.</li>
|
||
<li><strong>Fixed arrays are values.</strong> <code>[n T]</code> is inline storage
|
||
and copies on assignment and on pass-by-value.</li>
|
||
<li><strong>Slices are views.</strong> <code>[T]</code> is ptr+len and owns nothing.
|
||
Copying a slice copies the view, never the elements.</li>
|
||
<li><strong>Pointers are visible.</strong> <code>(addr x)</code> takes the address of
|
||
any assignable place and gives <code>(Ptr T)</code>. It does not extend anything's
|
||
lifetime, and keeping one past its frame is your contract to honour — there is no
|
||
borrow checker.</li>
|
||
</ul>
|
||
|
||
<p>A value struct is shared mutably by passing its address down the call chain. No
|
||
heap is involved.</p>
|
||
|
||
<p>Places — the forms <code>set</code> accepts — are a fixed list, not an extensible
|
||
<code>setf</code>:</p>
|
||
|
||
<pre><code>(defstruct Enemy [hp i32 name string])
|
||
|
||
(defvar spawned i32)
|
||
(defconst room-size 4)
|
||
(defvar room [room-size i32])
|
||
|
||
;; `set` takes a fixed list of forms, not an extensible setf.
|
||
(defn main [] ()
|
||
(let [e (Enemy {.hp 10 .name "slime"})
|
||
p (addr e)]
|
||
(set spawned (+ spawned 1)) ; a local or a defvar
|
||
(set (.hp e) 7) ; a struct field
|
||
(set (.hp p) 8) ; through a (Ptr Enemy) — derefs one level
|
||
(set (at room 2) 5) ; a fixed array or slice element
|
||
(set (deref p) (Enemy {.hp 3 .name "wisp"})) ; a whole-object store
|
||
|
||
(print (.hp e)) (println "")
|
||
(println (.name e))
|
||
(print (at room 2)) (println "")
|
||
(print spawned) (println "")))</code></pre>
|
||
|
||
<pre><code class="sh">3
|
||
wisp
|
||
5
|
||
1</code></pre>
|
||
|
||
<p><code>.field</code> and <code>at</code> dereference exactly one pointer level, so
|
||
<code>(set (.hp p) 8)</code> above is legal when <code>p</code> is a
|
||
<code>(Ptr Enemy)</code>. The whole-object store through <code>p</code> overwrote
|
||
<code>e</code> itself, so <code>hp</code> reads 3 and not 8.</p>
|
||
|
||
<h3>Bounds are checked</h3>
|
||
|
||
<pre><code>(defconst xs [3 i32] [1 2 3])
|
||
|
||
;; (at xs 7) with a literal index does not reach the backend at all: check.ml
|
||
;; rejects it. This one goes through a local, so it is the runtime check that
|
||
;; catches it — the same message, and the program stops where it happened.
|
||
(defn main [] ()
|
||
(let [i 7]
|
||
(println "before")
|
||
(print (at xs i))
|
||
(println "unreachable")))</code></pre>
|
||
|
||
<pre><code class="sh">$ flan run bounds.flan
|
||
before
|
||
bounds.flan:9:19: index 7 is out of bounds for length 3
|
||
$ echo $?
|
||
134</code></pre>
|
||
|
||
<p><code>at</code> and <code>slice</code> emit a comparison and a branch to a cold
|
||
block that names the source location and stops. Checks are on by default and are not
|
||
tied to the optimisation level. <code>--no-bounds-checks</code> turns them off.
|
||
Measured cost on a
|
||
50-million-iteration dependency chain over a 1024-element array: 0.11–0.12s checked
|
||
against 0.12–0.13s unchecked.</p>
|
||
|
||
<h2 id="types">Types</h2>
|
||
|
||
<p>Types are annotated at function boundaries and inferred everywhere else. Every type
|
||
notation reads as exactly one data item.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Notation</th><th>Meaning</th><th>Layout</th></tr>
|
||
<tr><td><code>i8</code> … <code>i64</code>, <code>u8</code> … <code>u64</code></td><td>machine integers, wrapping arithmetic</td><td>the obvious one</td></tr>
|
||
<tr><td><code>f32</code>, <code>f64</code></td><td>floats</td><td><code>float</code>, <code>double</code></td></tr>
|
||
<tr><td><code>bool</code></td><td></td><td><code>i1</code></td></tr>
|
||
<tr><td><code>string</code></td><td>a byte slice with no NUL</td><td>ptr + len</td></tr>
|
||
<tr><td><code>[T]</code></td><td>slice, non-owning</td><td>ptr + len</td></tr>
|
||
<tr><td><code>[n T]</code></td><td>fixed array, a value</td><td>n inline items</td></tr>
|
||
<tr><td><code>(Vec T)</code></td><td>growable, owning — <em>moves</em> on assignment</td><td>ptr + len + cap + its allocator</td></tr>
|
||
<tr><td><code>(Map K V)</code></td><td>open addressing, owning — <em>moves</em>. The only map spelling: braces in type position are not a type</td><td>data + len + log2cap + its allocator</td></tr>
|
||
<tr><td><code>(Pool T)</code></td><td>generational slab storage, owning — <em>moves</em></td><td>items + slots + its allocator</td></tr>
|
||
<tr><td><code>(Handle T)</code></td><td>a reference into a pool that reports a dead referent</td><td>index and generation packed into an <code>i64</code></td></tr>
|
||
<tr><td><code>(Ptr T)</code></td><td>raw pointer</td><td>a pointer</td></tr>
|
||
<tr><td><code>(Option T)</code></td><td><code>Some</code> / <code>None</code></td><td>tag byte + T</td></tr>
|
||
<tr><td><code>(Fn [T ...] R)</code></td><td>a function value</td><td>a pointer</td></tr>
|
||
<tr><td><code>Allocator</code></td><td>an opaque builtin: a proc, its data and a capability set</td><td>a pointer to that</td></tr>
|
||
<tr><td><code>$t</code></td><td>a type variable — see <a href="#generics">generics</a></td><td>whatever it is instantiated at</td></tr>
|
||
<tr><td>a struct</td><td>value type</td><td>fields in declaration order</td></tr>
|
||
<tr><td>a union</td><td><code>defunion</code>, matched by case</td><td>tag + the widest payload</td></tr>
|
||
<tr><td>an enum</td><td>its own type in the checker</td><td><code>i32</code></td></tr>
|
||
<tr><td><code>()</code></td><td>one value, zero size</td><td>empty</td></tr>
|
||
<tr><td><code>Never</code></td><td>fits anywhere; nothing has it</td><td>empty</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p><strong>There is no implicit widening.</strong> Both operands of a binary operator
|
||
have one type, and every conversion is written as a cast:</p>
|
||
|
||
<pre><code>(defn main [] i32
|
||
(let [n 40 ; i32, inferred
|
||
big (i64 n) ; every widening is written
|
||
x 1.5] ; f64
|
||
(print (+ big 2)) (println "")
|
||
(print (* x 2.5)) (println "")
|
||
(print (bit-xor (<< 1 8) 255)) (println "")
|
||
0))</code></pre>
|
||
|
||
<pre><code class="sh">42
|
||
3.75
|
||
511</code></pre>
|
||
|
||
<p>An untyped integer literal is <code>i32</code> and an untyped float literal is
|
||
<code>f64</code>, so <code>(defconst gravity f32 0.05)</code> names the type when
|
||
something narrower is wanted. One caveat: a whole-numbered float prints without its
|
||
fraction, so <code>3.0</code> comes out as <code>3</code>.</p>
|
||
|
||
<p>Arithmetic wraps. Shifts are bounded two ways: a literal count at or past the
|
||
operand's width is a compile error, and a computed one is masked to the width.
|
||
<code>>></code> is arithmetic on a signed type and logical on an unsigned
|
||
one.</p>
|
||
|
||
<p>An index converts from a narrower integer and never from a wider one. A
|
||
<code>u32</code> index is fine — anything above 2<sup>31</sup> truncates to a negative
|
||
<code>i32</code> and the unsigned bounds check rejects it. An <code>i64</code> index is
|
||
refused:</p>
|
||
|
||
<pre><code class="sh">an index is an i32, and i64 is wider — write (i32 …), because a value that does
|
||
not fit truncates to one that does and would read the wrong element without
|
||
tripping the bounds check</code></pre>
|
||
|
||
<h2 id="structs">Structs and enums</h2>
|
||
|
||
<p>A <code>defstruct</code> is a list of inline name/type pairs. A struct literal names
|
||
its fields, and omitted fields are zeroed.</p>
|
||
|
||
<pre><code>(defstruct Cursor
|
||
[src [u8] ; a non-owning slice
|
||
pos i32]) ; no initialiser means zeroed
|
||
|
||
(defn peek [c (Ptr Cursor)] u8
|
||
(if (< (.pos c) (len (.src c)))
|
||
(at (.src c) (.pos c))
|
||
0))
|
||
|
||
(defn advance [c (Ptr Cursor)] ()
|
||
(set (.pos c) (+ (.pos c) 1))) ; field access derefs one level
|
||
|
||
(defn main [] ()
|
||
(let [c (Cursor {.src (bytes "hi")})] ; pos omitted, so pos is 0
|
||
(print (peek (addr c))) (println "")
|
||
(advance (addr c))
|
||
(print (peek (addr c))) (println "")))</code></pre>
|
||
|
||
<pre><code class="sh">104
|
||
105</code></pre>
|
||
|
||
<p>Those are the bytes <code>h</code> and <code>i</code>. There is no character type — a
|
||
byte is a <code>u8</code> — but there is a byte literal, so <code>\h</code> is 104 and
|
||
<code>\space</code> is 32, and the prelude's <code>digit?</code> reads as
|
||
<code>(and (>= b \0) (<= b \9))</code>. To see a byte as a letter rather than as a
|
||
number, print a slice of them: <code>print</code> writes a <code>[u8]</code> as
|
||
its bytes.</p>
|
||
|
||
<p>An enum is an <code>i32</code> at run time and its own type in the checker. A
|
||
keyword at a call site resolves against the parameter's enum type at compile time, so a
|
||
typo is an error there rather than a wrong number later.</p>
|
||
|
||
<pre><code>(defenum Key
|
||
[space 32 escape 256 left 263 right 262])
|
||
|
||
(defn key-name [k Key] string
|
||
(cond
|
||
(= k :space) "space"
|
||
(= k :escape) "escape"
|
||
:else "an arrow"))
|
||
|
||
(defn main [] ()
|
||
;; :space resolves against the parameter's enum at compile time.
|
||
;; A typo is an error here, not a wrong number later.
|
||
(println (key-name :space))
|
||
(println (key-name :left)))</code></pre>
|
||
|
||
<pre><code class="sh">space
|
||
an arrow</code></pre>
|
||
|
||
<p>A keyword means nothing where no enum is expected. There is no keyword type to fall
|
||
back on, and there is no way to name a member other than as a keyword in a position
|
||
that expects that enum.</p>
|
||
|
||
<p>Struct and enum names share one top-level namespace with functions, globals and type
|
||
aliases. A second declaration of a name is rejected whatever kind either one is.</p>
|
||
|
||
<h2 id="functions">Functions</h2>
|
||
|
||
<p><code>(defn name [param Type ...] ReturnType body ...)</code>. The parameters are
|
||
inline name/type pairs, as in <code>let</code> and <code>defstruct</code>. The return
|
||
type is always written, and a function that returns nothing writes <code>()</code>,
|
||
which is unit. There is no separate <code>declare</code> form for a function with a
|
||
body — <code>declare</code> is kept only where there is none.</p>
|
||
|
||
<p>The slot used to be optional, and the parser decided return-type-versus-body by
|
||
looking the name up in a table of the file's types. It was sound only because one
|
||
top-level namespace means a name cannot be both a type and a value, and it was
|
||
silently wrong twice — once reading <code>(Rune {.code 65})</code> at the head of a
|
||
body as the function's return type. Writing the type removes the guess, and a
|
||
mistyped one now says <em>did you mean f64</em> rather than <em>unknown name</em>.</p>
|
||
|
||
<p>Top-level names are order-independent within a package, so mutually recursive
|
||
functions need no forward declaration. Globals come in two kinds:</p>
|
||
|
||
<pre><code>(defconst cell-size 5) ; a compile-time constant
|
||
(defconst gravity f32 0.05) ; with its type named
|
||
(defvar current-color i32) ; zeroed storage
|
||
(defconst rows 3)
|
||
(defconst cols 4)
|
||
(defvar grid [rows [cols u32]]) ; BSS, rows*cols*4 bytes
|
||
|
||
(defn main [] ()
|
||
(print cell-size) (println "")
|
||
(print gravity) (println "")
|
||
(print current-color) (println "")
|
||
(print (at grid 2 3)) (println ""))</code></pre>
|
||
|
||
<pre><code class="sh">5
|
||
0.05
|
||
0
|
||
0</code></pre>
|
||
|
||
<p>A <code>defconst</code> the checker consumed — an array length, for instance — is
|
||
part of the shape of the program. One it did not is only ever bytes in memory. The
|
||
two reload differently; see <a href="#devloop">the dev loop</a>.</p>
|
||
|
||
<p><code>let</code> binds name/value pairs and takes no type annotation, so a constant
|
||
whose type matters is named at the top level rather than written inline.</p>
|
||
|
||
<h2 id="control">Control flow</h2>
|
||
|
||
<p><code>if</code>, <code>when</code>, <code>unless</code>, <code>cond</code>,
|
||
<code>do</code>, <code>and</code>, <code>or</code>, <code>not</code>,
|
||
<code>while</code>, <code>until</code>, <code>dotimes</code>, <code>loop</code>/<code>recur</code>,
|
||
<code>break</code>, <code>continue</code>, <code>return</code>,
|
||
<code>match</code>. <code>and</code> and <code>or</code> short-circuit.
|
||
<code>:else</code> is <code>cond</code>'s catch-all.</p>
|
||
|
||
<pre><code>(defconst nums [5 i32] [1 3 8 9 10])
|
||
|
||
(defn classify [n i32] string
|
||
(cond
|
||
(< n 0) "negative"
|
||
(= n 0) "zero"
|
||
:else "positive"))
|
||
|
||
(defn countdown [n i32] ()
|
||
(let [i n]
|
||
(while (> i 0)
|
||
(print i)
|
||
(print " ")
|
||
(set i (- i 1)))
|
||
(println "")))
|
||
|
||
(defn first-even [s [i32]] (Option i32)
|
||
(dotimes [i (len s)]
|
||
(when (= 0 (% (at s i) 2))
|
||
(return (Some (at s i)))))
|
||
None)
|
||
|
||
(defn main [] ()
|
||
(println (classify -3))
|
||
(countdown 4)
|
||
(unless false
|
||
(println "unless runs when the test is false"))
|
||
(match (first-even (slice nums 0 (len nums)))
|
||
(Some n) (do (print n) (println ""))
|
||
None (println "none")))</code></pre>
|
||
|
||
<pre><code class="sh">negative
|
||
4 3 2 1
|
||
unless runs when the test is false
|
||
8</code></pre>
|
||
|
||
<p><code>dotimes</code> evaluates its bound once into a hidden slot before the loop, so
|
||
a body that changes it cannot change the trip count, and the loop variable is not
|
||
assignable.</p>
|
||
|
||
<p><code>break</code> and <code>continue</code> leave or restart the innermost loop, and
|
||
take a <strong>label</strong> when that is not the one meant. <code>loop</code> and
|
||
<code>recur</code> are the functional shape beside them: <code>loop</code> is an
|
||
<em>expression</em>, its value is the value of its body, and <code>recur</code> rebinds
|
||
every name at once and jumps rather than calls — ten million iterations do not grow the
|
||
stack.</p>
|
||
|
||
<pre><code>(defn gcd [a i32 b i32] i32
|
||
(loop [x a y b] ; recur rebinds every name at once
|
||
(if (= y 0) x (recur y (% x y)))))
|
||
|
||
(defn main [] ()
|
||
(println (gcd 84 36))
|
||
|
||
;; loop is an expression: its value is the value of the body.
|
||
(println (loop [i 0 acc 0]
|
||
(if (= i 5) acc (recur (+ i 1) (+ acc i)))))
|
||
|
||
;; continue in a dotimes advances the counter on the skipped iteration too.
|
||
(let [sum 0]
|
||
(dotimes [k 5]
|
||
(when (= k 2) (continue))
|
||
(set sum (+ sum k)))
|
||
(println sum))
|
||
|
||
;; A label says which loop. Unlabelled, break leaves the innermost.
|
||
(dotimes :outer [a 3]
|
||
(dotimes [b 3]
|
||
(when (= b 2) (break :outer))
|
||
(println b))))</code></pre>
|
||
|
||
<pre><code class="sh">12
|
||
10
|
||
8
|
||
0
|
||
1</code></pre>
|
||
|
||
<p><code>return</code> is still the way out of a <em>function</em> from inside a loop,
|
||
as <code>first-even</code> does above.</p>
|
||
|
||
<h3>Option, <code>match</code> and <code>some</code></h3>
|
||
|
||
<p><code>(Option T)</code> is how absence is spelled: a lookup miss, an empty
|
||
collection, the end of a stream. <code>match</code> works on an <code>Option</code> and
|
||
on a <code>defunion</code>, and on nothing else. <code>some</code> unwraps
|
||
<code>Some</code> and early-returns <code>None</code> from the enclosing function.</p>
|
||
|
||
<pre><code>(defconst nums [4 i32] [4 8 15 16])
|
||
|
||
;; `some` unwraps Some and early-returns None from *this* function.
|
||
(defn doubled-first [s [i32]] (Option i32)
|
||
(Some (* 2 (some (index-of s 15)))))
|
||
|
||
(defn main [] ()
|
||
(match (doubled-first (slice nums 0 4))
|
||
(Some i) (do (print i) (println "")) ; 4
|
||
None (println "not found"))
|
||
(match (index-of (slice nums 0 4) 99)
|
||
(Some i) (do (print i) (println ""))
|
||
None (println "not found")))</code></pre>
|
||
|
||
<pre><code class="sh">4
|
||
not found</code></pre>
|
||
|
||
<h2 id="defer">defer</h2>
|
||
|
||
<p>A <code>defer</code> runs at function exit, innermost first. An explicit
|
||
<code>return</code> runs the ones registered above it — a defer written below a return
|
||
has not executed yet and must not fire.</p>
|
||
|
||
<pre><code>(defn work [n i32] i32
|
||
(defer (println "second"))
|
||
(defer (println "first")) ; innermost-first at exit
|
||
(when (< n 0)
|
||
(return 0)) ; runs both defers above it
|
||
(println "body")
|
||
n)
|
||
|
||
(defn main [] ()
|
||
(print (work 3))
|
||
(println ""))</code></pre>
|
||
|
||
<pre><code class="sh">body
|
||
first
|
||
second
|
||
3</code></pre>
|
||
|
||
<p><code>defer</code> is function-scoped: it is copied into every exit path of the
|
||
function, so it always registers and always runs at function exit. It is therefore
|
||
<strong>rejected</strong> inside a loop or a branch, where "always registers" would be a
|
||
lie. A <code>let</code> is fine, and that is not an exception — a <code>let</code> is not
|
||
a frame here, its bindings are function slots like any other and nothing is released at
|
||
scope exit, so a <code>defer</code> written in one has exactly the function's extent.
|
||
That is the shape the permission exists for: acquire, defer the release beside it, then
|
||
use it.</p>
|
||
|
||
<pre><code class="sh">defer is not allowed inside a branch — a defer is copied into every exit path of
|
||
the function, so it always registers and always runs at function exit. Write it at
|
||
the top level of the function body, or in a let that is (a let has the function's
|
||
extent, because nothing is released at scope exit)</code></pre>
|
||
|
||
<h2 id="arrays">Arrays and slices</h2>
|
||
|
||
<p><code>at</code> indexes a fixed array or a slice, and takes any number of
|
||
indices, so <code>(at grid r c)</code> indexes a two-dimensional fixed array directly.
|
||
It is a place: <code>(set (at grid r c) v)</code> and <code>(addr (at grid r c))</code> both work.
|
||
<code>len</code> works on a fixed array, a slice or a string.
|
||
<code>(slice s lo hi)</code> takes a half-open range and never copies.</p>
|
||
|
||
<pre><code>(defconst rows 3)
|
||
(defconst cols 4)
|
||
|
||
;; A fixed array is a value: inline storage, copies on assignment.
|
||
(defconst palette [4 u32] [0xE6B800FF 0x3B6E8CFF 0xA83232FF 0xCC6B1FFF])
|
||
|
||
;; No initialiser means all-bytes-zero, so this is BSS and costs nothing.
|
||
(defvar grid [rows [cols i32]])
|
||
|
||
(defn main [] ()
|
||
(set (at grid 1 2) 7)
|
||
(print (at grid 1 2)) (println "") ; 7
|
||
(print (len palette)) (println "") ; 4
|
||
|
||
;; A slice is ptr+len and non-owning: it views the array, it does not copy it.
|
||
(let [row (slice (at grid 1) 0 cols)]
|
||
(set (at row 0) 5)
|
||
(print (at grid 1 0)) (println "") ; 5 — the same storage
|
||
(print (sum-i32 row)) (println "")) ; 12
|
||
|
||
;; (zeroed) is a memset, not an allocation.
|
||
(set grid (zeroed))
|
||
(print (at grid 1 2)) (println "")) ; 0</code></pre>
|
||
|
||
<pre><code class="sh">7
|
||
4
|
||
5
|
||
12
|
||
0</code></pre>
|
||
|
||
<p>A reversed range — <code>lo</code> greater than <code>hi</code> — traps, rather than
|
||
yielding a huge unsigned length.</p>
|
||
|
||
<h2 id="generics">Generics</h2>
|
||
|
||
<p>Parametric polymorphism by monomorphisation: one body is written, and every call
|
||
site gets a copy compiled at the types it passed. There are no type classes, no
|
||
dictionaries and nothing decided at run time.</p>
|
||
|
||
<p><strong>A type variable is written <code>$t</code> where a type goes</strong> — a
|
||
parameter's type, the return type, or nested inside a type constructor such as
|
||
<code>[$t]</code> or <code>(Vec $t)</code>. The sigil is not a binding-site-only
|
||
spelling: every type position writes it. <strong>Bare <code>t</code> is the same
|
||
variable in <em>expression</em> position</strong>, where a builtin takes the name of a
|
||
type as an argument — <code>(vec-new t)</code>, <code>(map-new t i32)</code>,
|
||
<code>(pool-new t)</code>, and the cast <code>(t x)</code>.</p>
|
||
|
||
<pre><code>(defn ident [x $t] $t x) ; needs nothing declared
|
||
|
||
(defn twice [x $t] $t ; + - * / % need numeric?
|
||
{:where (numeric? $t)}
|
||
(+ x x))
|
||
|
||
(defn clamp-to [x $t lo $t hi $t] $t ; < <= > >= min max need ordered?
|
||
{:where (ordered? $t)}
|
||
(min (max x lo) hi))
|
||
|
||
(defn first-or [s [$t] d $t] $t ; the variable inside a slice type
|
||
{:where (copyable? $t)}
|
||
(if (= (len s) 0) d (at s 0)))
|
||
|
||
(defn one-of [x $t] (Vec $t) ; bare t is the type-name argument
|
||
{:where (copyable? $t)}
|
||
(let [v (vec-new t)]
|
||
(push v x)
|
||
v))
|
||
|
||
(defn main [] ()
|
||
(println (ident 3))
|
||
(println (ident "text"))
|
||
(println (twice 1.5))
|
||
(println (clamp-to 12 0 10))
|
||
(let [ns [5 3 9 1]
|
||
one (one-of 4.5)]
|
||
(println (first-or (slice ns 0 4) -1))
|
||
(println (at (as-slice one) 0))
|
||
(free one)))</code></pre>
|
||
|
||
<pre><code class="sh">3
|
||
text
|
||
3
|
||
10
|
||
5
|
||
4.5</code></pre>
|
||
|
||
<h3>The body is checked once, abstractly</h3>
|
||
|
||
<p>A generic body is checked <strong>with nothing substituted</strong>, so an operator
|
||
the variable is not declared to support is refused at the definition rather than at
|
||
whichever call site first reaches a type that happens to work. That is deliberately
|
||
<em>not</em> Odin's rule, which checks a polymorphic body per instantiation:</p>
|
||
|
||
<pre><code class="sh">+ over the type variable t is refused: a type variable supports only what it is
|
||
declared to support, and nothing here says t is numeric?. Write {:where (numeric?
|
||
$t)} at the head of the body, or take the operation as a parameter — a
|
||
(Fn [t t] ...) — and call it here</code></pre>
|
||
|
||
<p>What makes that liveable is a <code>where</code> clause, written as a Clojure-style
|
||
map at the head of the body — <code>{:where (ordered? $t)}</code>, or a vector when
|
||
there is more than one: <code>{:where [(copyable? $t) (copyable? $u)]}</code>. There
|
||
are five predicates, and each gates builtins the compiler already has:</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Predicate</th><th>What it admits</th></tr>
|
||
<tr><td><code>numeric?</code></td><td><code>+</code> <code>-</code> <code>*</code> <code>/</code> <code>%</code>, and a cast <code>(t x)</code></td></tr>
|
||
<tr><td><code>ordered?</code></td><td><code><</code> <code><=</code> <code>></code> <code>>=</code> <code>min</code> <code>max</code></td></tr>
|
||
<tr><td><code>equal?</code></td><td><code>=</code> and <code>!=</code></td></tr>
|
||
<tr><td><code>hashable?</code></td><td>the variable as a <code>Map</code> key — <code>(map-new t V)</code>, <code>get</code>, <code>put</code>, <code>has-key?</code></td></tr>
|
||
<tr><td><code>copyable?</code></td><td>reading the value more than once; <code>Pool</code> and <code>Vec</code> element positions</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>They entail each other in one direction, so one clause usually does:
|
||
<code>numeric?</code> gives <code>ordered?</code>, <code>ordered?</code> gives
|
||
<code>equal?</code>, and any of the four gives <code>copyable?</code>. A
|
||
<code>sort!</code> that compares its elements and reads them twice declares
|
||
<code>ordered?</code> and nothing else.</p>
|
||
|
||
<p><strong>A type variable is move-only by default</strong>, and
|
||
<code>copyable?</code> is the opt-out. <code>Types.is_move_only</code> of a variable is
|
||
not decidable abstractly — the same variable is <code>i32</code> at one instantiation
|
||
and <code>(Vec i32)</code> at the next — so the checker assumes the stricter rule,
|
||
which can only refuse a program that would have been fine and never admit one that
|
||
double-frees. It is Rust's <code>T: Copy</code>, with the difference that the compiler
|
||
answers the question rather than a user implementing a trait. So
|
||
<code>(defn twice [x $t] $t (+ x x))</code> does not merely want
|
||
<code>numeric?</code>; reading <code>x</code> a second time is a use after move:</p>
|
||
|
||
<pre><code class="sh">x was moved at twice.flan:1:26 and cannot be used again — t is move-only, so
|
||
binding, passing or returning one transfers ownership and the source binding is
|
||
dead afterwards (spec-memory.md). That rule is what makes a double free
|
||
unrepresentable; (clone x) if you wanted a second one</code></pre>
|
||
|
||
<p>Each instantiation then checks the concrete type against what the signature declared,
|
||
and refuses the <em>call site</em> when it does not answer:</p>
|
||
|
||
<pre><code class="sh">this call instantiates twice at $t = bool, and bool does not answer numeric? —
|
||
which twice requires, being written {:where (numeric? $t)}. The requirement is the
|
||
signature's, so the refusal is here, at the call that asked for the type: pass one
|
||
the predicate admits</code></pre>
|
||
|
||
<p>Two forms are deferred to the instantiation rather than settled abstractly, because
|
||
their legality is only decidable after substituting: <code>println</code> over a
|
||
variable, which selects the structural printer per copy, and the <code>Map</code>
|
||
operations over a variable key, whose hash and equality are concrete symbols chosen from
|
||
the concrete key type. The <code>Map</code> half is what <code>hashable?</code> buys —
|
||
without the clause, the type <code>(Map $t i32)</code> is refused where it is
|
||
<em>written</em>, and with it the refusal moves to the call site that names an
|
||
unhashable key.</p>
|
||
|
||
<p>This is not a type class and the difference is worth keeping straight. A type class
|
||
carries <em>implementations</em>, selected per instance and extensible by anyone, and
|
||
needs dictionaries and coherence rules. A predicate carries nothing — it gates a builtin
|
||
that already exists. The ceiling is that nobody can supply a <code><</code> of their
|
||
own; every operation the prelude and the containers need is a primitive, so it does not
|
||
bind. <code>test/programs/generics.flan</code> exercises the whole of it.</p>
|
||
|
||
<h2 id="printing">Printing</h2>
|
||
|
||
<p><code>println</code> prints a value and a newline; <code>print</code> is the same
|
||
walk without the newline. There is one of each and they take any type, but neither is a
|
||
function and neither is overloading: the compiler walks the argument's type where the
|
||
call is written and emits the printing for it. Nothing is decided at run time — a Flan
|
||
value carries no header, so nothing at run time could say what it is — and there is no
|
||
user-supplied printer to choose between.</p>
|
||
|
||
<pre><code>(defenum Key [space 32 left 263])
|
||
(defstruct Enemy [hp i32 name string key Key])
|
||
|
||
(defn look-up [k Key] (Option i32)
|
||
(if (= k :space) (Some 32) None))
|
||
|
||
(defn main [] ()
|
||
(println 42) ; an i32, uncast
|
||
(println 1.5)
|
||
(println (Enemy {.hp 3 .name "wisp" .key :left}))
|
||
(println (look-up :space))
|
||
(println (look-up :left))
|
||
(print "no newline: ") (println true))</code></pre>
|
||
|
||
<pre><code class="sh">42
|
||
1.5
|
||
(Enemy {:hp 3 :name "wisp" :key :left})
|
||
(some 32)
|
||
none
|
||
no newline: true</code></pre>
|
||
|
||
<p>The walk covers every integer and float type, <code>bool</code>, <code>()</code>,
|
||
<code>string</code>, <code>[u8]</code>, enums, <code>Ptr</code>, <code>Option</code>,
|
||
structs, unions, fixed arrays and slices. An owning container has no printer for its
|
||
contents and comes back as a marker instead — <code><vec></code>,
|
||
<code><pool></code>, <code><allocator></code> — while a <code>Handle</code>
|
||
shows its index and generation, and a <code>Map</code> has no printer at all.
|
||
An enum member comes back as its name: the value is
|
||
an <code>i32</code> by the time the backend sees it, so the name is recovered here from
|
||
the checker's table, and a value outside the declared members falls through to the
|
||
number, which is what you would want to see. A <code>Ptr</code> prints as
|
||
<code><ptr></code> and is never followed — it is the one thing that could make
|
||
the walk cycle, and dereferencing a pointer on someone else's behalf is not safe.</p>
|
||
|
||
<p>A string prints raw at the top level and quoted-and-escaped inside a structure.
|
||
Those are not in conflict: <code>(println "hello")</code> has to print
|
||
<code>hello</code> or it is useless, and the <code>name</code> field above has to be
|
||
quoted or it could not be told from the punctuation around it.</p>
|
||
|
||
<p>The walk is bounded in depth and in span, so a deeply nested value or a
|
||
<code>[100 [100 u32]]</code> grid prints <code>...</code> rather than a screenful — and,
|
||
since the walk is unrolled at compile time, rather than putting ten thousand printing
|
||
sites in the module.</p>
|
||
|
||
<p>That the walk takes the argument's own type matters more here than it would in a
|
||
language that widens implicitly. Nothing widens implicitly in this one, so a printer
|
||
that named a type would need a cast written at every call — and a <code>u64</code>
|
||
above 2<sup>63</sup> put through a signed one comes out negative. <code>print</code>
|
||
takes the value as it is and prints the number it holds.</p>
|
||
|
||
<h2 id="prelude">The prelude</h2>
|
||
|
||
<p>The prelude is written in Flan, all but five lines of it, and prepended to every
|
||
program, so nothing in it needs importing. It holds no printing of its own:
|
||
<code>print</code> and <code>println</code> are the compiler's, and
|
||
<code>write-stdout</code> — the one output primitive — is what they are written
|
||
over.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Group</th><th>Names</th></tr>
|
||
<tr><td>slice algorithms, over one type variable</td><td><code>swap!</code>, <code>reverse!</code>, <code>sort!</code>, <code>sort-by!</code>, <code>index-of</code>, <code>min-of</code>, <code>max-of</code>, <code>map!</code>, <code>reduce</code>, <code>filter</code></td></tr>
|
||
<tr><td>the per-type layer that stays</td><td><code>sum-i32</code>, <code>sum-f32</code> — the element and the accumulator are different types, which one variable cannot say</td></tr>
|
||
<tr><td>bytes</td><td><code>bytes=?</code>, <code>bytes<?</code>, <code>bytes-ci=?</code>, <code>starts-with?</code>, <code>ends-with?</code>, <code>index-of-bytes</code>, <code>trim</code>, <code>digit?</code>, <code>space?</code>, <code>sort-bytes!</code></td></tr>
|
||
<tr><td>parsing</td><td><code>parse-i64</code>, <code>parse-f64</code></td></tr>
|
||
<tr><td>text</td><td><code>split-on-byte</code>, <code>split-next!</code>, <code>split</code>, <code>lower-ascii</code>, <code>upper-ascii</code>, <code>to-lower</code>, <code>to-upper</code></td></tr>
|
||
<tr><td>building bytes</td><td><code>append!</code>, <code>append-i64!</code>, <code>append-f64!</code>, <code>concat</code>, <code>join</code>, <code>repeat-bytes</code>, <code>replace-bytes</code>, <code>slices-new</code>, <code>format-f64</code></td></tr>
|
||
<tr><td>UTF-8</td><td><code>decode-rune</code>, <code>rune-at</code>, <code>rune-count</code>, <code>rune-size</code>, <code>rune-start?</code>, <code>valid-utf8?</code>, <code>encode-rune!</code></td></tr>
|
||
<tr><td>numbers</td><td><code>sign-f32</code>, <code>lerp</code>, <code>clamp</code>, <code>floor-f32</code>, <code>ceil-f32</code>, <code>round-f32</code>, and the five <code>declare</code>s: <code>sqrt-f32</code>, <code>sin-f32</code>, <code>cos-f32</code>, <code>atan2-f32</code>, <code>pow-f32</code></td></tr>
|
||
<tr><td>random</td><td><code>rand-seed</code>, <code>rand-u32</code>, <code>rand-f32</code>, <code>rand-i32-range</code>, <code>rand-f32-range</code></td></tr>
|
||
<tr><td>forms, for macros</td><td><code>form-nil</code>, <code>form-cons</code>, <code>form-append</code>, <code>form-rest</code>, <code>form-items</code>, <code>form-pair</code>, <code>form-sym?</code>, <code>form-is-sym?</code>, <code>gensym</code>, and <code>unless</code> and <code>into</code>, which are macros written here rather than special forms</td></tr>
|
||
<tr><td>the rest</td><td><code>pause</code>, which signals the <code>Pause</code> condition the break loop stops on, and <code>embed-find</code></td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p><strong>One family, not one per type.</strong> The slice algorithms used to be
|
||
<code>sort-i32!</code> beside <code>sort-f32!</code> beside <code>sort-bytes!</code>, and
|
||
generics collapsed them: <code>sort!</code> is written once and instantiated at whatever
|
||
element type the call passes. <code>sum-i32</code> and <code>sum-f32</code> are what did
|
||
<em>not</em> collapse, and they are the honest exception — each widens its element into a
|
||
different accumulator, which one variable cannot express.</p>
|
||
|
||
<p><strong>The RNG is ours, not libc's</strong> — PCG-XSH-RR 32, written in Flan —
|
||
because a grid hash is only a regression test if the sequence is byte-identical on
|
||
native and on wasm32. <strong>The parsers are ours too</strong>:
|
||
<code>strtoll</code> answers 0 for <code>""</code>, 0 for
|
||
<code>"abc"</code> and 12 for <code>"12x"</code>, which are three wrong answers a caller
|
||
cannot tell from a real 12.</p>
|
||
|
||
<p>Five functions in the file are not Flan, and they are libm's:
|
||
<code>(declare sqrt-f32 [x f32] f32 "sqrtf")</code> and the same line for
|
||
<code>sinf</code>, <code>cosf</code>, <code>atan2f</code> and <code>powf</code>. Every
|
||
other number here is reachable from the four operations and a cast; a square root is
|
||
not, and the usual trick of seeding Newton's method from the exponent bits needs a
|
||
bit-cast between <code>f32</code> and <code>u32</code> that the language does not have.
|
||
IEEE-754 makes <code>sqrt</code> correctly rounded, so libm gives the same bit pattern
|
||
on both targets anyway. <strong>The other four are not</strong>: IEEE-754 requires
|
||
nothing of <code>sinf</code>, <code>cosf</code>, <code>atan2f</code> or
|
||
<code>powf</code>, and glibc, musl and wasi-libc do differ in the last bit — so the
|
||
byte-identical-hash property the RNG exists for does not survive a hash routed through
|
||
any of them. Every link carries <code>-lm</code>.</p>
|
||
|
||
<p>The primitives underneath are few — a primitive is the only thing implemented
|
||
twice per backend: <code>argv</code>,
|
||
<code>write-stdout</code>, <code>exit</code>, <code>len</code>, <code>at</code>,
|
||
<code>slice</code>, <code>bytes</code>, <code>bytes->f64</code>,
|
||
<code>bytes->i64</code>, <code>f64->bytes</code>, <code>i64->bytes</code>,
|
||
<code>addr</code>, and arithmetic, comparison and casts.</p>
|
||
|
||
<h2 id="packages">Packages</h2>
|
||
|
||
<p><strong>The directory is the package.</strong> Every file in a directory shares one
|
||
top-level scope; files within a package do not import each other, and their order does
|
||
not matter. The package declaration is optional and the name is inferred from the
|
||
directory, so a loose file in a scratch directory is a package of one with no manifest
|
||
and no ceremony.</p>
|
||
|
||
<pre><code>;; geom/vec.flan — no package declaration: the name comes from the directory.
|
||
(defstruct V2 [x f32 y f32])
|
||
|
||
(defn add [a V2 b V2] V2
|
||
(V2 {.x (+ (.x a) (.x b)) .y (+ (.y a) (.y b))}))</code></pre>
|
||
|
||
<pre><code>;; geom/len.flan — a second file in the same directory shares one top-level
|
||
;; scope: it does not import vec.flan, and the order of the two does not matter.
|
||
(defn length [v V2] f32
|
||
(sqrt-f32 (+ (* (.x v) (.x v)) (* (.y v) (.y v)))))</code></pre>
|
||
|
||
<pre><code>;; pkg.flan — the directory is the package, and everything it declares
|
||
;; arrives qualified by the alias this import chose.
|
||
(import g "geom")
|
||
|
||
(defn main [] ()
|
||
(let [v (g/add (g/V2 {.x 3.0 .y 0.0})
|
||
(g/V2 {.x 0.0 .y 4.0}))]
|
||
(print (g/length v))
|
||
(println "")))</code></pre>
|
||
|
||
<pre><code class="sh">5</code></pre>
|
||
|
||
<p>There is one form and one meaning: <code>(import alias "path")</code>, and everything
|
||
from the package is qualified <code>alias/name</code>. There is no unqualified-import
|
||
mode, no <code>:refer</code>, no <code>ns</code> form and no per-file namespace object.
|
||
A path with no collection prefix is relative to the importing file;
|
||
<code>vendor:</code> and <code>core:</code> are collections, resolved by walking up from
|
||
the importing file until a directory of that name is found.</p>
|
||
|
||
<p>Importing is a rename. Every top-level name the package declares becomes
|
||
<code>alias/name</code>, and every use of one — in a type, in a body, in a struct
|
||
literal, in an array length — is rewritten to match. Nothing downstream knows a package
|
||
existed.</p>
|
||
|
||
<p>Three more rules:</p>
|
||
|
||
<ul>
|
||
<li><strong>A package may be a single <code>.flan</code> file</strong> named outright,
|
||
for the program that is also a library. <code>sand.flan</code> shares a directory with
|
||
three other loose programs, so naming its directory would import all four.</li>
|
||
<li><strong>A package may import a package</strong>, and the qualification flattens to
|
||
the inner alias: raylib imported by a package that is itself imported is still
|
||
<code>rl/…</code>. A directory is keyed by its real path and read once, so a cycle
|
||
ends there. The same directory under two different aliases is refused.</li>
|
||
<li><strong><code>main</code> is not exported.</strong> A package carrying one would
|
||
collide with the importer's, and <code>main</code> is a reachability root, so an
|
||
imported one would keep everything it calls alive. Writing <code>sand/main</code> is
|
||
refused at the line that wrote it.</li>
|
||
</ul>
|
||
|
||
<p>Visibility is that one rule and no more: there is no package-private marker for
|
||
anything other than <code>main</code> yet.</p>
|
||
|
||
<p>A package may carry the C it binds to. Every <code>.c</code> file in the directory is
|
||
compiled into the build, and a file named <code>link</code> lists extra linker
|
||
arguments. Whether those reach the build is decided after checking, from the program
|
||
rather than from the import list: the compiler starts at <code>main</code>, follows every
|
||
call, and a package none of whose externs survive contributes no C and no linker
|
||
argument, so a file that imports raylib still builds for wasm32.</p>
|
||
|
||
</div>
|
||
|
||
<div class="panel" id="panel-conditions">
|
||
|
||
<h2 id="conditions">Conditions and restarts</h2>
|
||
|
||
<p>A condition is a struct. There is no class hierarchy; matching is by type. The
|
||
signalling end says <em>here is something notable, here is the data</em>, and an outer
|
||
caller decides what to do about it — or decides nothing, in which case the signaller
|
||
carries on.</p>
|
||
|
||
<pre><code>(signal c) ; (). Handler returns -> carry on. No handler -> no-op.
|
||
(error c) ; Never. Only a transfer gets past; else the program stops.
|
||
|
||
(handler-bind [(Type [c] body ...) ...] body ...) ; match by type, no hierarchy
|
||
|
||
(restart-case BODY ; BODY and every clause have the same type = the form's
|
||
(name [p T ...] CLAUSE) ...)
|
||
|
||
(invoke-restart 'name arg ...) ; Never. Innermost frame offering the name wins.</code></pre>
|
||
|
||
<p><code>signal</code> has type <code>()</code>, always. A handler that returns
|
||
normally leaves the signaller to carry on — the accumulation case:</p>
|
||
|
||
<pre><code>(defstruct AssetMissing [id i32])
|
||
|
||
(defvar seen i64)
|
||
|
||
(defn load-all [] ()
|
||
(signal (AssetMissing {.id 1})) ; () — the caller carries on
|
||
(signal (AssetMissing {.id 2})))
|
||
|
||
(defn main [] ()
|
||
(load-all) ; no handler: a no-op
|
||
(print seen) (println "") ; 0
|
||
|
||
;; A handler that returns normally accumulates and lets the signaller run on.
|
||
(handler-bind [(AssetMissing [c] (set seen (+ seen (i64 (.id c)))))]
|
||
(load-all))
|
||
(print seen) (println "")) ; 3</code></pre>
|
||
|
||
<pre><code class="sh">0
|
||
3</code></pre>
|
||
|
||
<p>A handler that invokes a restart instead transfers control outward to the
|
||
<code>restart-case</code> that offers the name, and the clause's value becomes that
|
||
form's value. Every <code>defer</code> between the invoke and the target runs, innermost
|
||
first, before the clause body starts.</p>
|
||
|
||
<pre><code>(defstruct AssetMissing [id i32])
|
||
|
||
(defvar cleanups i64)
|
||
|
||
(defn load [n i32] i32
|
||
(signal (AssetMissing {.id n}))
|
||
100)
|
||
|
||
(defn middle [n i32] i32
|
||
(defer (set cleanups (+ cleanups 1))) ; runs on the transfer too
|
||
(+ (load n) 1))
|
||
|
||
(defn fetch [n i32] i32
|
||
(restart-case (middle n) ; its value if nothing transfers
|
||
(use-placeholder [] -1)
|
||
(retry [] 7)))
|
||
|
||
(defn main [] ()
|
||
(print (fetch 1)) (println "") ; 101 — nothing handled it
|
||
|
||
(handler-bind [(AssetMissing [c] (invoke-restart 'use-placeholder))]
|
||
(print (fetch 2)) (println "")) ; -1
|
||
|
||
(print cleanups) (println "")) ; 2 — the defer ran both times</code></pre>
|
||
|
||
<pre><code class="sh">101
|
||
-1
|
||
2</code></pre>
|
||
|
||
<p>A clause may take parameters, which is how the answer comes from <em>outside</em> the
|
||
frame that offers the restart:</p>
|
||
|
||
<pre><code>(defn supplied [n i32] i32
|
||
(restart-case (middle n)
|
||
(use-value [v i32] (* v 2)) ; the handler supplies v
|
||
(retry [] 7)))
|
||
|
||
(defn main [] ()
|
||
(handler-bind [(AssetMissing [c] (invoke-restart 'use-value 21))]
|
||
(println (supplied 7)))) ; 42</code></pre>
|
||
|
||
<pre><code class="sh">42</code></pre>
|
||
|
||
<p>Restart lookup walks the dynamic restart stack from innermost outward and takes the
|
||
first frame offering the name, so an inner <code>restart-case</code> shadows an outer
|
||
one for the duration of its body. An inner parser's <code>skip-form</code> is found
|
||
before an outer one's.</p>
|
||
|
||
<h3>How a transfer is lowered</h3>
|
||
|
||
<p>A transfer is not platform unwinding. Every Flan signature carries a transfer channel
|
||
— one pointer appended as an out-parameter — which <code>invoke-restart</code> writes
|
||
and every call site checks. A callee writes the target into its caller's slot; each
|
||
frame checks, runs its defers and returns early. The disassembly is the release one plus
|
||
a guard after each call.</p>
|
||
|
||
<p>Three consequences:</p>
|
||
|
||
<ul>
|
||
<li><strong>wasm32 works with no exception proposal</strong>, and native and wasm
|
||
builds of the same program agree.</li>
|
||
<li><strong>Every function carries the channel, release builds included.</strong> A
|
||
hot-reload cell holds a bare pointer, so the honest answer to "what can this call?" is
|
||
"anything". A later optimisation may stop a function checking the channel; it may not
|
||
drop the parameter.</li>
|
||
<li><strong>A transfer cannot cross a foreign frame.</strong> A handler installed
|
||
across an FFI boundary must return normally.</li>
|
||
</ul>
|
||
|
||
<h3>Gotchas</h3>
|
||
|
||
<ul>
|
||
<li><strong>A handler closes over nothing.</strong> A clause is lifted into a function
|
||
of its own, because it runs from wherever the signal was. Accumulate into a global, or
|
||
put the value on the condition. A reference to an enclosing local is refused for that
|
||
reason rather than reported as an unknown name.</li>
|
||
<li><strong>A restart is not a transaction.</strong> Control resumes at the
|
||
<code>restart-case</code> and runs forward from there, so a <code>retry</code> repeats
|
||
every side effect between it and the target. Nothing rolls back — a global the frame
|
||
already set stays set, and is set again. Common Lisp has exactly this property and
|
||
offers no help either.
|
||
<p>So the author chooses where the retry boundary is. A <code>restart-case</code> at the
|
||
top of a frame re-runs everything including mutations already applied; one placed after
|
||
the mutations re-runs only what follows. Put the restart before anything mutates, make
|
||
the retried section idempotent, or snapshot what will be re-applied.
|
||
<code>test/programs/frame-rollback.flan</code> is the worked example of the snapshot, and
|
||
the ordering in it is the part worth reading: restore <em>in the restart clause</em> and
|
||
not in a <code>defer</code>, because a defer runs on the ordinary return path too and
|
||
that version silently rolls back the frames that succeeded.</p>
|
||
<p>This matters more here than in most Lisps because the intended use is a
|
||
<em>game loop</em>, where the plan is to skip a frame and carry on rather than die. Now
|
||
that a bad index signals <code>BoundsError</code> instead of ending the process,
|
||
abandoning a frame and retrying it is a real thing to do — and that is exactly the case
|
||
a non-idempotent mutation spoils.</p></li>
|
||
<li><strong>An unknown restart name is a hard stop</strong> — a located runtime error.
|
||
There is no <code>find-restart</code> to test with yet.</li>
|
||
<li><strong>No supertype</strong>, so nothing can say "any condition".</li>
|
||
<li><strong><code>signal</code> cannot hand a value back.</strong> Deliberate: the
|
||
alternative forces every signal site to declare a default value and a result type.</li>
|
||
<li><strong><code>return</code> is refused inside a <code>handler-bind</code> or
|
||
<code>restart-case</code> body</strong>, and so is <code>invoke-restart</code> inside a
|
||
<code>defer</code>. In each case a bare exit would leave frames on the stack pointing
|
||
into a function that has gone.</li>
|
||
<li><strong>A restart's parameters are checked at run time</strong>, count then
|
||
spelling, because a restart is found by name on a dynamic stack and neither end can see
|
||
the other. Lookup is by the name alone and the signature is checked after it, so an
|
||
inner <code>(use-value [s string] …)</code> shadows an outer
|
||
<code>(use-value [v i32] …)</code> and <code>(invoke-restart 'use-value 21)</code>
|
||
stops the program even though the outer clause would have taken it. The clause's
|
||
parameters are slots of the function that wrote it, and the invoker fills a buffer that
|
||
function owns — by the time a clause runs, the invoking frame has gone.</li>
|
||
</ul>
|
||
|
||
<h2 id="break">The break loop</h2>
|
||
|
||
<p>An <code>error</code> nothing handles does not kill the program. It stops on the
|
||
frame that erred, with nothing unwound, so the condition and every restart between there
|
||
and the top are still live:</p>
|
||
|
||
<pre><code class="sh">flan: unhandled Missing — stopped, not dead.
|
||
0. restart: retry
|
||
1. restart: use-placeholder</code></pre>
|
||
|
||
<p>From there you fix the function, install it, and take a restart. The numbers are
|
||
how one is taken: a restart is chosen by position, because an inner one may shadow an
|
||
outer one of the same name and a name alone could not tell you which you were getting.
|
||
Control never left the erring frame, so <code>retry</code> calls through the
|
||
indirection cell and reaches the new body. Installing while stopped is allowed; there is no frame in progress.</p>
|
||
|
||
<p>The break loop lives in <code>vendor/agent</code>, which is an optional package. A
|
||
program that does not import it leaves the hook null and stops the old way — the message
|
||
and an exit status of 134:</p>
|
||
|
||
<pre><code>(defstruct Missing [id i32])
|
||
|
||
(defn load [n i32] i32
|
||
(restart-case
|
||
(do (error (Missing {.id n})) ; Never — only a transfer gets past
|
||
0)
|
||
(use-placeholder [] -1)
|
||
(retry [] 7)))
|
||
|
||
(defn main [] ()
|
||
(print (load 1))
|
||
(println ""))</code></pre>
|
||
|
||
<pre><code class="sh">$ flan run boom.flan
|
||
unhandled Missing
|
||
$ echo $?
|
||
134</code></pre>
|
||
|
||
</div>
|
||
|
||
<div class="panel" id="panel-ffi">
|
||
|
||
<h2 id="ffi">The FFI</h2>
|
||
|
||
<p>There are two declaration forms, and they are two forms rather than one because no
|
||
structural rule could tell them apart.</p>
|
||
|
||
<p><code>declare</code> names a C symbol in a signature Flan can already spell. Nothing
|
||
is generated; a Flan string crosses as ptr+len, exactly as it is stored.</p>
|
||
|
||
<pre><code>(declare cos-f64 [x f64] f64 "cos")
|
||
|
||
(defn main [] ()
|
||
(print (cos-f64 0.0)) (println ""))</code></pre>
|
||
|
||
<pre><code class="sh">1</code></pre>
|
||
|
||
<p>That is 1.0, printed by the same rule as before.</p>
|
||
|
||
<p><code>declare-c</code> names the C library's own function in the C library's own
|
||
signature, and the compiler writes the wrapper. This is what raylib's package is made
|
||
of — one line per binding:</p>
|
||
|
||
<pre><code>(declare-c unload-texture [texture Texture2D] "UnloadTexture")
|
||
|
||
(declare-c draw-texture
|
||
[texture Texture2D x i32 y i32 tint Color]
|
||
"DrawTexture")</code></pre>
|
||
|
||
<p><strong>An aggregate's calling convention is not part of its layout.</strong> On
|
||
x86-64, clang gives raylib's own prototypes
|
||
<code><2 x float></code> for a returned <code>Vector2</code>, <code>i32</code> for
|
||
a <code>Color</code> argument, and <code>{ i64, i64 }</code> for a returned
|
||
<code>Rectangle</code> — none of which is the struct's own LLVM type, and arm64 and
|
||
wasm32 classify differently again. Reproducing that in the backend would be three
|
||
classifiers to write and keep correct forever, and a mistake would show up as a field
|
||
full of garbage rather than as a link error.</p>
|
||
|
||
<p>So the boundary has one wrapper per binding, each flattening the aggregates: a struct
|
||
returns through an out-pointer, a struct argument is passed by pointer, and clang
|
||
classifies all of it, per target, for free. <code>flan shim <file></code> prints
|
||
the whole generated file, of which this is the end — the rest is the typedefs
|
||
and a comment saying not to edit it:</p>
|
||
|
||
<pre><code>(defstruct Vector2 [x f32 y f32])
|
||
|
||
(declare-c get-mouse-position [] Vector2 "GetMousePosition")</code></pre>
|
||
|
||
<pre><code class="c">typedef struct flan_ty_Vector2_1bebc5ae_s flan_ty_Vector2_1bebc5ae;
|
||
|
||
struct flan_ty_Vector2_1bebc5ae_s { /* Vector2 */
|
||
float x;
|
||
float y;
|
||
};
|
||
|
||
/* get-mouse-position */
|
||
extern flan_ty_Vector2_1bebc5ae GetMousePosition(void);
|
||
void flan_shim_get_mouse_position_5ad0e205(flan_ty_Vector2_1bebc5ae *out) {
|
||
*out = GetMousePosition();
|
||
}</code></pre>
|
||
|
||
<p>A build needs the shared library to be linkable and <em>not</em> the
|
||
<code>-devel</code> package to be installed: every declaration a package uses is written
|
||
down in the package itself, so nothing has to go looking for a system header.
|
||
<strong>Guaranteed:</strong> the C typedef
|
||
and the Flan struct come from the same <code>defstruct</code>, so they cannot disagree,
|
||
and clang type-checks the wrapper against the generated prototype.
|
||
<strong>Trusted:</strong> that the <code>defstruct</code> matches the library's real
|
||
struct, and that the <code>declare-c</code> signature is the function's real signature.
|
||
A scalar's width now carries ABI weight — <code>f64</code> where the library says
|
||
<code>float</code> emits <code>double</code>, and the library reads garbage. That
|
||
trusted half is what the generator below checks.</p>
|
||
|
||
<h3>Generated bindings, committed</h3>
|
||
|
||
<p>Writing a binding per function by hand does not scale past the ones a program
|
||
happens to call, so most of raylib's package is not written by hand. A package
|
||
directory may carry a <code>headers</code> file naming the library's own C header;
|
||
<code>flan generate-c <package-dir></code> reads it with
|
||
<code>clang -Xclang -ast-dump=json</code>, turns every function it can represent into
|
||
the same <code>declare-c</code> line a person would have written, and writes them to
|
||
<code>generated.flan</code> in the package — which is <em>committed</em>.</p>
|
||
|
||
<pre><code class="sh">$ flan generate-c vendor/raylib
|
||
wrote vendor/raylib/generated.flan: 269 declarations, 117 refused, of 581 functions
|
||
in vendor/raylib/raylib-5.5.h.
|
||
Every defstruct, every hand-written declare-c and every mapped
|
||
constant agrees with it.</code></pre>
|
||
|
||
<p>Committing the output is what makes the declarations a dependency of the repository
|
||
rather than of the machine: every build gets all of them, they are greppable, and they
|
||
show up in a diff when the library moves. The argument is not caching — the clang dump
|
||
is already cached on disk and in memory.</p>
|
||
|
||
<p><strong>The header is committed too</strong>, at
|
||
<code>vendor/raylib/raylib-5.5.h</code>, and <code>headers</code> names it by path with
|
||
no environment variable in front of it. That line used to be
|
||
<code>?${FLAN_RAYLIB_H}</code> — optional, on the argument that requiring a header would
|
||
cost everyone the no-<code>-devel</code> property in order to give the check to whoever
|
||
had one. Committing the header dissolved that argument, because nobody needs
|
||
<code>raylib-devel</code> to have a file that ships with the repository. So the check now
|
||
runs on <strong>every</strong> build, and delete the header and the build says so by
|
||
name rather than going quiet. What being optional actually cost was found the hard way:
|
||
a gitignored web directory meant several working trees were checking against nothing and
|
||
were not told, and a check that silently does not run is worse than no check.</p>
|
||
|
||
<p><strong>Regeneration is the stronger check.</strong> An ordinary build re-reads every
|
||
declaration against the header, but only the hand-written ones can disagree — the
|
||
generated half came out of that header and agrees with it by construction. The one
|
||
function that <em>writes</em> the file therefore compares first and <em>refuses to
|
||
write</em> when the package and the header disagree: every <code>defstruct</code>
|
||
against the header's record, and every hand-written <code>declare-c</code> against the
|
||
header's signature. Pointed at a raylib 5.1-dev header while the package is written for
|
||
5.5, it reports ten real differences and writes nothing — which is exactly the silent
|
||
version skew a generated file would otherwise bake in and make look reviewed.</p>
|
||
|
||
<p>This is also why the hand-written bindings are kept rather than replaced by generated
|
||
ones. Everything the generator emits agrees with the header by construction, so diffing
|
||
generated output against the header it came from proves nothing; the hand-written lines
|
||
were transcribed by a person, so they are the only declarations a header can actually
|
||
contradict. All ten of those differences came from them.</p>
|
||
|
||
<p>A committed generated file cannot be hand-corrected — the next regeneration destroys
|
||
the edit without telling anybody — so the corrections live in a <code>bindings</code>
|
||
file beside <code>headers</code>, which is read <em>while</em> the declarations are made.
|
||
Two directives:</p>
|
||
|
||
<pre><code class="sh"># raylib's own malloc/realloc/free, which would be a second untracked heap
|
||
# behind three innocuous Flan names.
|
||
exclude Mem*
|
||
|
||
# The kebab rule gives is-window-ready. Lisp spells a predicate with a ?.
|
||
name IsWindowReady window-ready?</code></pre>
|
||
|
||
<p>An excluded function still says it was excluded rather than going quiet, and a name
|
||
override changes only the Flan face — the C symbol is kept verbatim in the declaration,
|
||
so it is still what is called and still what the check compares. Renaming is also the
|
||
way out of a collision: <code>Spin2D</code> and <code>spin2d</code> both kebab to
|
||
<code>spin-2d</code>, so neither takes the name, because which one won would otherwise
|
||
depend on the order the header happens to declare them in.</p>
|
||
|
||
<p>Anything neither directive can express is a hand-written <code>declare-c</code> in the
|
||
package's own source, which wins over the generated file and is left alone by the
|
||
generator. That is the escape hatch for a signature the importer gets wrong and for a
|
||
Flan face the header cannot describe — raylib keeps two, each a raw binding wrapped by a
|
||
Flan function of the same name, one taking a slice and one answering with an
|
||
<code>Option</code>.</p>
|
||
|
||
<p>Everything the boundary cannot represent is refused by name with the reason, rather
|
||
than half-supported: an <code>Option</code>, a union, a fixed array, a map, a returned
|
||
string, a callback, a slice parameter, an unknown type, an unrepresentable struct field,
|
||
and two Flan names for one C symbol. An aggregate in a plain <code>declare</code> is
|
||
refused too, so the narrow boundary cannot quietly acquire one.</p>
|
||
|
||
<p>One known edge: a REPL redefinition that introduces a <em>new</em>
|
||
<code>declare-c</code> cannot work, because the reload path compiles no C and the wrapper
|
||
would not exist in the running process. Editing the body of a function that calls an
|
||
existing binding is unaffected.</p>
|
||
|
||
</div>
|
||
|
||
<div class="panel" id="panel-devloop">
|
||
|
||
<h2 id="devloop">The dev loop</h2>
|
||
|
||
<p>Edit the code, keep the sand.</p>
|
||
|
||
<pre><code class="sh">$ flan dev sand.flan</code></pre>
|
||
|
||
<p>That builds the program, launches it, holds a session beside it, and listens on
|
||
<code>.flan-dev.sock</code> next to the source. From Emacs, <kbd>C-c C-c</kbd> on a
|
||
function recompiles it and installs it into the running process at that process's next
|
||
frame boundary. The window does not blink and the grid does not reset.</p>
|
||
|
||
<h3>How it works</h3>
|
||
|
||
<p>Four pieces, each runnable on its own.</p>
|
||
|
||
<p><strong>The reload primitive.</strong> <code>llc</code> → <code>ld -shared</code> →
|
||
<code>dlopen</code> → call. Measured in this codebase:</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Step</th><th>Cost</th></tr>
|
||
<tr><td>emitting the redefinition's IR</td><td>below the timer (<0.1ms)</td></tr>
|
||
<tr><td><code>llc -O2 -filetype=obj</code></td><td>15–17ms</td></tr>
|
||
<tr><td><code>ld -shared</code></td><td>3ms</td></tr>
|
||
<tr><td><code>dlopen</code> + <code>dlsym</code></td><td>0.04ms</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>About 19ms end to end. The <code>clang</code> driver on the same IR is 50ms, so the
|
||
dev path never invokes it. The driver forks a second process and re-does argument and
|
||
target resolution; codegen is not the cost.</p>
|
||
|
||
<p><strong>Indirection cells.</strong> Loading a new body is not installing it. A call
|
||
bound at link time cannot be made to notice one, so a <code>--dev</code> build routes
|
||
every Flan-to-Flan call through a cell — a mutable global holding the address of the
|
||
function that is current.</p>
|
||
|
||
<p>Here is the <code>defer</code> example from <a href="#defer">above</a> — its
|
||
<code>main</code> calls <code>work</code> — through <code>flan emit --dev</code>:</p>
|
||
|
||
<pre><code class="llvm">@"flan.cell.work" = global ptr @"flan.work"
|
||
|
||
define {} @"flan.main"(ptr %xfer) {
|
||
entry:
|
||
%t7 = alloca %slice
|
||
%t1 = load ptr, ptr @"flan.cell.work"
|
||
%t2 = call i32 %t1(i32 3, ptr %xfer)</code></pre>
|
||
|
||
<p>The call site loads the cell rather than naming <code>@"flan.work"</code>
|
||
directly. The signature carries <code>ptr %xfer</code> — the transfer channel from
|
||
<a href="#conditions">conditions</a>, on every Flan function, release builds
|
||
included. <code>println</code> is not in there: it is not a Flan function, so there is
|
||
no call to route and no cell for it.</p>
|
||
|
||
<p>Redefinition is then one store, below a microsecond. Three rules follow. A
|
||
redefinition module declares every <em>global</em> external, so globals live in the host
|
||
and survive a reload. Every other function is a <code>declare</code>, so a redefined
|
||
<code>settle</code> calls the host's <code>move-grain</code> rather than freezing a
|
||
private copy of it. And nothing is ever <code>dlclose</code>d: a cell holds an address
|
||
inside a module's text, so unloading it would leave call sites pointing at unmapped
|
||
memory. Old code is never unloaded, so a thread mid-execution finishes safely in the old
|
||
version.</p>
|
||
|
||
<p><strong>The agent.</strong> <code>vendor/agent</code> is a package like any other: a
|
||
listener thread, a single-producer ring, and three calls. This is the whole of
|
||
<code>agent.flan</code> — no aggregate crosses the boundary, so a plain
|
||
<code>declare</code> does it and there is no shim.</p>
|
||
|
||
<pre><code>(declare start-raw [path string] i32 "flan_agent_start")
|
||
(declare poll-raw [] i32 "flan_agent_poll")
|
||
(declare wait-raw [ms i32] i32 "flan_agent_wait")
|
||
|
||
(defn start [path string] i32 (start-raw path))
|
||
(defn poll [] i32 (poll-raw))
|
||
(defn wait [ms i32] i32 (wait-raw ms))</code></pre>
|
||
|
||
<p><code>(agent/start path)</code> listens on a unix socket, once, at startup.
|
||
<code>(agent/poll)</code> installs whatever has arrived and returns how many.
|
||
<code>(agent/wait ms)</code> is the same but waits for something first. A headless test
|
||
uses it so that a reload is deterministic rather than a race against the frame rate.</p>
|
||
|
||
<p>Loading and installing are separate. <code>dlopen</code> relocates
|
||
a module and takes the loader lock — milliseconds, unbounded — so it happens on the
|
||
listener thread. Installing is one store per function and must not land while a redefined
|
||
function is on the stack, so it happens on the game thread, at the top of the frame, when
|
||
the program asks. A game loop calls <code>agent/poll</code> at the top of its frame and
|
||
ignores the result.</p>
|
||
|
||
<p><strong>The session and the daemon.</strong> <code>flan dev</code> holds the
|
||
declarations the running process was built from plus every change accepted since, and it
|
||
owns the build, so its rules describe the process that is actually running. Re-checking
|
||
the whole program on every evaluation costs under 10ms, less than the <code>llc</code>
|
||
that follows. An evaluation is transactional: a form that fails to check mutates
|
||
nothing.</p>
|
||
|
||
<p>The protocol is one s-expression per message, length-framed by a decimal byte count.
|
||
It is not nREPL: <code>eval</code> there is string-in/string-out with no slot for
|
||
<em>which form, from which file</em>, and once the editor client is ours too there is no
|
||
CIDER to be compatible with.</p>
|
||
|
||
<h3>What a running process cannot be told</h3>
|
||
|
||
<p>Some changes are refused with a reason rather than loaded, because the alternative is
|
||
a silent mismatch against memory the process has already laid out:</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Change</th><th>What it would have broken</th></tr>
|
||
<tr><td>a function's signature</td><td>a cell is a bare pointer; every call site compiled before the change still passes the old arguments through it</td></tr>
|
||
<tr><td>a global's type</td><td>the storage exists and has a shape — reuse reads at the wrong offsets, replacement discards the state the reload exists to preserve</td></tr>
|
||
<tr><td>a struct's fields</td><td>the values the process is holding have the old layout</td></tr>
|
||
<tr><td>a <code>defconst</code> the checker consumed</td><td>it is in the shape of the program — <code>(defconst rows (/ h c))</code> decides <code>grid</code>'s type before anything else resolves</td></tr>
|
||
<tr><td>a <code>defenum</code> member</td><td><code>:space</code> is erased to an <code>i32</code> literal in the caller, so it is folded there too</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>A <code>defvar</code>'s <em>initial value</em> is deliberately not on that list:
|
||
its storage holds state the program moved past long ago. And a <code>defconst</code>
|
||
the checker never consumed can be changed, so a colour table can be tuned live while an
|
||
array length stays refused. A dev build emits those as mutable globals, so LLVM cannot
|
||
fold a read of one.</p>
|
||
|
||
<p>The signature row is a stopgap. The design is versioned functions with their own
|
||
trampolines, so that new callers resolve the new version while existing ones keep the
|
||
old. None of the three parts exists yet, and the alternative to refusing is a silent
|
||
argument mismatch.</p>
|
||
|
||
<h3>Evaluating an expression</h3>
|
||
|
||
<p><kbd>C-x C-e</kbd> is a different primitive from redefining a name. There is no name
|
||
to install a body into, so the expression is wrapped in a thunk with nowhere to be called
|
||
from. The module says <em>run this once</em>, and the agent calls it after the install, on
|
||
the game thread, at a frame boundary. An expression reading the program's state therefore
|
||
sees a consistent one.</p>
|
||
|
||
<p>Nothing is marshalled back, because nothing could be: a Flan value carries no header,
|
||
so no code at run time can say what it is. The compiler knows the type and renders it
|
||
there, in the thunk. What comes back looks like this:</p>
|
||
|
||
<pre><code class="sh">big 18446744073709551615
|
||
col :blue
|
||
(.pos b) (V {:x 1.5 :y 0})
|
||
b (Blob {:id 7 :name "sandy \"quoted\"" :pos (V {:x 1.5 :y 0}) :tags [ 0 42 0]})
|
||
(slice (.tags b) 0 3) [ 0 42 0]
|
||
(rl/get-color 0x11223344) (rl/Color {:r 17 :g 34 :b 51 :a 68})
|
||
sim/grid [ [ 0 0 0 0 0 0 0 0 ...] [ 0 ... ] ...]</code></pre>
|
||
|
||
<p>A pointer is never followed; it renders as <code><ptr></code>. Following one
|
||
would make the walk cycle, and dereferencing a pointer a REPL was handed is not safe.
|
||
The walk is bounded at depth 4 and 8 elements, and the output truncates at 4K. An owning
|
||
container renders as a marker rather than its contents — <code><vec></code>,
|
||
<code><pool></code>, <code><allocator></code>, <code><handle 3:1></code>
|
||
— and a function value renders as its signature, because the inspector reaches every local
|
||
of a stopped frame and a frame holding one has to render rather than refuse. A
|
||
<code>Map</code> is what still refuses by name.</p>
|
||
|
||
<p>The thunk's module is unloaded afterwards. Nothing points into its text once it has
|
||
returned. Sixteen expression evaluations retain zero mappings, where each redefinition
|
||
retains three, permanently and correctly.</p>
|
||
|
||
<h2 id="emacs">Emacs</h2>
|
||
|
||
<p><code>emacs/flan-mode.el</code> derives from <code>prog-mode</code> with
|
||
<code>lisp-mode</code>'s syntax table, so sexp motion, paren matching and indentation are
|
||
already right. It adds Flan's brackets — <code>[</code> and <code>{</code> are brackets,
|
||
not symbol characters, since every binding list and every type is written with them — and
|
||
the characters a Flan name may contain. <code>emacs/flan-dev.el</code> is the client;
|
||
there is no parser in it.</p>
|
||
|
||
<h3>Setting up</h3>
|
||
|
||
<p>Put <code>emacs/</code> on your load path and require the mode. Nothing else is needed:
|
||
the client, the REPL, the inspector and the conditions buffer all load on first use.</p>
|
||
|
||
<pre><code class="sh">(add-to-list 'load-path "~/Development/flan/emacs")
|
||
(require 'flan-mode)
|
||
(require 'flan-dape) ; optional — lldb, and the only thing that binds C-c C-g</code></pre>
|
||
|
||
<p><code>flan-dape.el</code> is separate on purpose, so <code>flan-mode</code> works
|
||
without dape installed. You also need <code>flan</code> on your <code>PATH</code>, or
|
||
<code>flan-dev-command</code> pointed at it.</p>
|
||
|
||
<h3>Starting a program</h3>
|
||
|
||
<p><code>M-x flan-dev</code> runs <code>flan dev</code> on a file, waits for it to come up
|
||
and connects. <kbd>C-c C-z</kbd> attaches to one that is already running, looking for
|
||
<code>.flan-dev.sock</code> upward from the buffer, so from anywhere in the project it
|
||
finds the one program you have going. <kbd>C-c C-q</kbd> disconnects and leaves it
|
||
running; <code>M-x flan-dev-quit</code> stops it, but only one this Emacs started — a
|
||
daemon you launched in a terminal is not Emacs' to kill, and it says so rather than doing
|
||
something surprising.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Key</th><th>Does</th></tr>
|
||
<tr><td><kbd>C-c C-c</kbd></td><td>the top-level form at point, recompiled and installed</td></tr>
|
||
<tr><td><kbd>C-u C-c C-c</kbd></td><td>…and mark it, so the program stops at the form point is inside (<kbd>C-u C-u</kbd>: on entry)</td></tr>
|
||
<tr><td><kbd>C-c C-k</kbd></td><td>the whole buffer, as <em>one</em> module</td></tr>
|
||
<tr><td><kbd>C-x C-e</kbd></td><td>the expression before point, evaluated in the running program</td></tr>
|
||
<tr><td><kbd>C-u C-x C-e</kbd></td><td>…and stop <em>at</em> it instead of printing its value</td></tr>
|
||
<tr><td><kbd>C-c C-z</kbd> / <kbd>C-c C-q</kbd></td><td>connect (finds <code>.flan-dev.sock</code> upward) / disconnect</td></tr>
|
||
<tr><td><kbd>C-c C-o</kbd></td><td>the running program's own output, in <code>*flan-output*</code></td></tr>
|
||
<tr><td><kbd>C-c C-r</kbd></td><td>a prompt on the running program (<code>*flan-repl*</code>)</td></tr>
|
||
<tr><td><kbd>C-c C-b</kbd></td><td>a stopped program: the condition, the restarts, the stack</td></tr>
|
||
<tr><td><kbd>C-c C-M-b</kbd></td><td>the same restarts, as a one-key prompt</td></tr>
|
||
<tr><td><kbd>C-c C-i</kbd></td><td>inspect a value, navigating into its fields</td></tr>
|
||
<tr><td><kbd>C-c C-a</kbd></td><td>disassemble a function; <kbd>C-u</kbd> first for its LLVM IR</td></tr>
|
||
<tr><td><kbd>C-c C-g</kbd></td><td>debug under lldb, through dape — bound only once <code>flan-dape.el</code> is loaded, so <code>flan-mode</code> works without dape installed</td></tr>
|
||
<tr><td><kbd>C-c C-d</kbd></td><td>what the running program currently defines</td></tr>
|
||
<tr><td><kbd>C-c C-v</kbd></td><td>help on the name at point</td></tr>
|
||
<tr><td><kbd>C-c C-x</kbd></td><td>rebuild, relaunch and reconnect</td></tr>
|
||
<tr><td><kbd>M-.</kbd> / <kbd>M-,</kbd></td><td>where a name is written, through an <code>xref</code> backend</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>Some commands have no key. <code>M-x flan-dev</code> starts a program and
|
||
<code>M-x flan-dev-quit</code> stops it. <code>M-x flan-watch</code> opens the watch
|
||
buffer, which shows values <em>while the program runs</em> rather than while it is
|
||
stopped, and <code>M-x flan-watch-ghost-mode</code> shows the same values inline at the
|
||
call that wrote each one. <code>M-x flan-inspect-address</code> roots an inspection at a
|
||
raw address rather than at an expression. <code>M-x flan-allocations</code> and
|
||
<code>M-x flan-leaks</code> read the allocation registry: every block it recorded grouped
|
||
by type, and the same walk with the dead left out.</p>
|
||
|
||
<p><kbd>C-c C-k</kbd> sends one module rather than a form at a time on purpose: a
|
||
<code>defvar</code> and the function that uses it have to arrive in the same load, or the
|
||
first refers to storage that does not exist yet.</p>
|
||
|
||
<p><kbd>C-x C-e</kbd> compiles the expression before point and runs it <em>inside</em> the
|
||
running program — the actual process, with its actual state, not a copy. Both it and
|
||
<kbd>C-c C-c</kbd> work on buffer text rather than the saved file, and a change installs at
|
||
the next frame boundary.</p>
|
||
|
||
<h3>The buffers, and their own keys</h3>
|
||
|
||
<p>Three buffers have keymaps of their own. The conditions buffer
|
||
(<kbd>C-c C-b</kbd>) shows the condition, then the restarts, then the stack — in that
|
||
order, because the decision in front of you is which restart to take and the stack is only
|
||
the explanation for it.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Buffer</th><th>Keys</th></tr>
|
||
<tr><td>conditions</td>
|
||
<td><kbd>RET</kbd> take the restart at point · <kbd>0</kbd>–<kbd>9</kbd> take one by number ·
|
||
<kbd>TAB</kbd>/<kbd>n</kbd>, <kbd>S-TAB</kbd>/<kbd>p</kbd> move ·
|
||
<kbd>f</kbd> fold a frame · <kbd>i</kbd> inspect a local ·
|
||
<kbd>a</kbd> abort · <kbd>g</kbd> re-read · <kbd>q</kbd> close</td></tr>
|
||
<tr><td>inspector</td>
|
||
<td><kbd>RET</kbd> into the field at point · <kbd>l</kbd> back out ·
|
||
<kbd>g</kbd> re-read · <kbd>TAB</kbd>/<kbd>n</kbd>, <kbd>S-TAB</kbd>/<kbd>p</kbd> move ·
|
||
<kbd>q</kbd> close</td></tr>
|
||
<tr><td>repl</td>
|
||
<td><code>comint</code>, plus <kbd>C-c C-o</kbd>, <kbd>C-c C-d</kbd> and <kbd>C-c C-q</kbd></td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>A restart is taken by <em>position</em>, which is why the list is numbered: a name
|
||
resolves to the innermost frame offering it, so an outer <code>retry</code> shadowed by an
|
||
inner one is real, is on the list, and cannot be reached by name. One that genuinely cannot
|
||
be taken is drawn and refused with the reason rather than quietly omitted.</p>
|
||
|
||
<p>The inspector is unlike most: the view is never stale, because every step re-reads the
|
||
program as it is now. The cost is that <strong>the root expression runs again on every
|
||
step</strong> — going into a field sends <code>(.pos b)</code> where the last one sent
|
||
<code>b</code>, which is harmless, but inspecting <code>(spawn-enemy)</code> spawns one per
|
||
keystroke. That is why there is no auto-refresh and why <kbd>g</kbd> is a key you press.</p>
|
||
|
||
<p>The repl is program-scoped rather than buffer-scoped, so in sand you write
|
||
<code>sim/settle</code> and not <code>settle</code>. <code>*flan-output*</code> is separate
|
||
from it, because the program's stdout belongs to the program.</p>
|
||
|
||
<h3>When a change is refused</h3>
|
||
|
||
<p>Two different things wear the same refusal today, and only one of them is the design.</p>
|
||
|
||
<p><strong>A changed signature is a placeholder refusal.</strong> The intended behaviour,
|
||
and what <a href="#reading">plan.org</a> specifies, is that a signature change makes a new
|
||
version of the function: new callers resolve it, existing callers and any stored
|
||
<code>Fn</code> value stay safely on the old one, and the session <em>warns</em> at each
|
||
tracked stale caller site so you know what to re-evaluate. Nothing should have to restart.
|
||
That needs function versions, trampolines and caller tracking, none of which are built yet
|
||
— so until they are, the session refuses rather than letting a cell hand old arguments
|
||
to a new body. The refusal is a limitation with a date on it, not a rule.</p>
|
||
|
||
<p><strong>A changed struct layout is the genuinely hard case</strong>, and is rejected
|
||
while live values of that struct exist: storage already allocated has the old shape, and a
|
||
new body would read its fields at the wrong offsets with nothing to say so. plan.org keeps
|
||
this one as a rejection, and gives managed classes an explicit migration at a frame
|
||
boundary as the eventual way through.</p>
|
||
|
||
<p><kbd>C-c C-x</kbd> rebuilds, relaunches and reconnects, and is the way out while the
|
||
above is true. It costs the program's state, which is why it is a key you press rather than
|
||
something <kbd>C-c C-c</kbd> falls back to.</p>
|
||
|
||
<h3>Around the edges</h3>
|
||
|
||
<p>eldoc, completion and <kbd>M-.</kbd> all read one cached reply rather than asking per
|
||
keystroke, refreshed at the two moments the answer can have changed: on connect, and after
|
||
an evaluation the daemon accepted. The modeline says whether there is a program on the
|
||
other end, and says <code>stopped</code> when there is one sitting in the break loop — a
|
||
stopped program looks exactly like a running one from anywhere else in Emacs.</p>
|
||
|
||
<p>An error comes back with a location and the client draws an overlay there, cleared the
|
||
next time that buffer's evaluation is accepted. Under <kbd>C-c C-g</kbd> lldb needs no
|
||
plugin to read a Flan value, since a struct is its C struct; locals show under their real
|
||
names, and a shadowed one appears as <code>v~2</code> while plain <code>v</code> still
|
||
answers with the outer binding.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>Setting</th><th>Default</th><th>What it is</th></tr>
|
||
<tr><td><code>flan-dev-command</code></td><td><code>"flan"</code></td><td>the compiler binary</td></tr>
|
||
<tr><td><code>flan-dev-socket-name</code></td><td><code>".flan-dev.sock"</code></td><td>what <kbd>C-c C-z</kbd> searches for</td></tr>
|
||
<tr><td><code>flan-dev-echo-result</code></td><td><code>t</code></td><td>print <kbd>C-x C-e</kbd>'s value in the echo area</td></tr>
|
||
<tr><td><code>flan-dev-names-shown</code></td><td><code>4</code></td><td>how many names to list before counting them</td></tr>
|
||
<tr><td><code>flan-dev-output-buffer</code></td><td><code>"*flan-output*"</code></td><td>where the program's output goes</td></tr>
|
||
<tr><td><code>flan-dev-poll-interval</code></td><td><code>1.0</code></td><td>seconds between checks for whether it stopped</td></tr>
|
||
<tr><td><code>flan-dev-start-timeout</code></td><td><code>60</code></td><td>seconds to wait for a program to come up</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="panel" id="panel-builds">
|
||
|
||
<h2 id="targets">Targets and builds</h2>
|
||
|
||
<p>Native x86-64 is the development target. <code>--target=wasm32-wasi</code> produces a
|
||
module, and the headless sand acceptance program prints the same 64-bit hash under it as
|
||
it does natively:</p>
|
||
|
||
<pre><code class="sh">$ flan run test/programs/sand-headless.flan
|
||
15595743031174623232
|
||
$ flan build test/programs/sand-headless.flan --target=wasm32-wasi -o sand.wasm
|
||
$ node --no-warnings test/wasm-run.mjs sand.wasm
|
||
15595743031174623232</code></pre>
|
||
|
||
<p>The RNG is written in Flan rather than called from libc for that number: a grid hash
|
||
is only a regression test if the sequence is byte-identical on both targets. It holds at
|
||
<code>-O2</code> and at <code>-O0</code>. The wasm side needs a
|
||
<code>wasm32</code> builtins archive — from wasi-sdk, or emscripten's substituting for
|
||
it — and the compiler names every path it looked in when it cannot find one.</p>
|
||
|
||
<p>Dev and release builds are deliberately different. <code>--dev</code> means
|
||
indirection cells and <code>-rdynamic</code>, which exports those cells for a loaded
|
||
module to bind to. Release builds call directly, emit constants as constants, and get all
|
||
the folding back. Dev builds are not pruned by reachability: what a REPL may redefine
|
||
next is not a function of what has been called so far.</p>
|
||
|
||
<p><strong>There is a second backend, and it is off by default.</strong>
|
||
<code>flan build --x86</code> lowers the checked program to x86-64 by hand —
|
||
<code>lib/x86.ml</code>, writing an assembly file directly — instead of going through
|
||
LLVM. It is the <em>dev</em> backend: LLVM stays the default and stays the release path,
|
||
and the two never meet in one process, which is what lets the hand-written one pick its
|
||
own internal calling convention (every aggregate by pointer, no eightbyte rule, no
|
||
classifier) and match SysV only at the C boundary, where the shim has already flattened
|
||
every struct.</p>
|
||
|
||
<p>It covers a subset of the IR and <strong>refuses the rest by name</strong>, so a
|
||
build that succeeds is one it really compiled rather than one it half-compiled.
|
||
Conditions are the visible gap — anything reaching the transfer channel is refused:</p>
|
||
|
||
<pre><code class="sh">$ flan build test/programs/algorithms.flan --x86
|
||
Fatal error: exception Flan.X86.Unsupported("restart-case needs the transfer
|
||
channel, which this backend does not emit a guard for")</code></pre>
|
||
|
||
<p><code>--debug</code> is a third flag beside <code>--dev</code> and the optimisation
|
||
level. <code>--dev</code> asks whether you can redefine the program while it runs;
|
||
<code>--debug</code> asks whether you can stop it and read it. It emits DWARF, sets
|
||
<code>-O0</code>, and is refused by name for wasm32. lldb needs no plugin to read a
|
||
Flan struct: the struct is its C struct.</p>
|
||
|
||
<p>Some things are refused by name rather than half-supported, and both cross-target
|
||
refusals say why:</p>
|
||
|
||
<pre><code class="sh">$ flan run hello.flan --target=wasm32-wasi
|
||
flan run: --target is refused — a cross-built module is not something this host
|
||
can exec. Use flan build --target=... and a wasm runtime.
|
||
|
||
$ flan build hello.flan --dev --target=wasm32-wasi
|
||
wasm32: --dev is native only — the reload path is dlopen, which wasm32 has no
|
||
equivalent of</code></pre>
|
||
|
||
<p>Build time for <code>calc-me.flan</code> is about 110ms, of which the frontend — read,
|
||
parse, load, check, emit — is under 10ms. Every C translation unit goes through an object
|
||
cache keyed by a digest of the source text, the compiler, the optimisation level and the
|
||
target flags, so it never needs invalidating by hand.</p>
|
||
|
||
<h2 id="notyet">Not implemented yet</h2>
|
||
|
||
<p>The house rule is that anything which binds a name, alters control flow, or is not
|
||
yet implemented must be recognised explicitly and rejected. Each of these refuses by
|
||
name, with the milestone it belongs to, and the tests assert on the reason.</p>
|
||
|
||
<div class="scroll">
|
||
<table>
|
||
<tr><th>You write</th><th>The compiler says</th></tr>
|
||
<tr><td><code>(Result T E)</code></td><td>(Result T E) is not implemented yet — milestone 6 (see plan.org)</td></tr>
|
||
<tr><td><code>(try …)</code></td><td>try (Result) is not implemented yet — milestone 6 (see plan.org)</td></tr>
|
||
<tr><td><code>'sym</code> as a value</td><td>a quoted symbol (restart names) is not implemented yet — milestone 6 (see plan.org)</td></tr>
|
||
<tr><td>a bare lowercase type name</td><td>generic code over the type variable a is not implemented yet — milestone 5 (see plan.org)</td></tr>
|
||
<tr><td><code>errdefer</code></td><td>errdefer is not implemented yet (see the build sequence in plan.org)</td></tr>
|
||
<tr><td><code>await</code></td><td>await is not implemented yet (see the build sequence in plan.org)</td></tr>
|
||
<tr><td><code>handler-case</code></td><td>handler-case is not implemented yet (see the build sequence in plan.org)</td></tr>
|
||
<tr><td><code>find-restart</code>, <code>compute-restarts</code></td><td>… is not implemented yet (see the build sequence in plan.org)</td></tr>
|
||
<tr><td>a union as a <code>declare</code> parameter</td><td>a parameter of g is U, which cannot cross to C directly — pass (Ptr U) and let the shim read it</td></tr>
|
||
<tr><td>a user-written allocator</td><td>a user-written allocator is not implemented yet, and a defn's name in that position …</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>Two of those rows want reading carefully. <strong>A quoted symbol works where a
|
||
restart is named</strong> — <code>(invoke-restart 'use-value 21)</code> is the ordinary
|
||
spelling — and is refused only as a value in its own right, because there is no symbol
|
||
type to give it. And <strong>the type-variable row is about the sigil</strong>: bare
|
||
<code>a</code> in type position is not a type variable and never became one;
|
||
<code>$t</code> is, and <a href="#generics">generics</a> is where it is written down.</p>
|
||
|
||
<p>Beyond that list, and just as true: there is no overloading; <code>defer</code> is
|
||
refused inside a loop or a branch (a <code>let</code> is fine — it has the function's
|
||
extent); <code>find-restart</code> and <code>compute-restarts</code> are blocked on a
|
||
<code>Restart</code> type rather than on effort; a restart with parameters cannot be
|
||
taken from the break loop, which aims at a frame by position and has nothing to fill them
|
||
with; there is no package-private marker other than <code>main</code> not being exported;
|
||
there are no threads in the language; and the managed <code>class</code> facility that
|
||
plan.org describes is a plan and not a feature.</p>
|
||
|
||
<p>One of these is settled rather than pending. There is <strong>no interpreter</strong>
|
||
and there is not going to be one: compiling is the only way a form is ever run. The
|
||
instrumentation-based step debugger that wanted one is cut, and compiled redefinition at
|
||
~19ms is perceptually instant for expression evaluation too. That is also how macros run
|
||
— a <code>defmacro</code> is compiled into a shared object and dlopened into the
|
||
compiler before the file that calls it is expanded, so there is no second evaluator to
|
||
disagree with the first.</p>
|
||
|
||
<h2 id="reading">Further reading</h2>
|
||
|
||
<p>The repository's own documents, in the order they are worth reading:</p>
|
||
|
||
<ul>
|
||
<li><code>plan.org</code> — the design, the build sequence, and the open decisions.</li>
|
||
<li><code>NEXT.md</code> — the project's memory, and the authority on what is actually
|
||
built.</li>
|
||
<li><code>spec-memory.md</code> — ownership, containers, places, generics, function
|
||
values. Frozen.</li>
|
||
<li><code>spec-conditions.md</code> — conditions and restarts, operational semantics.
|
||
Frozen.</li>
|
||
<li><code>conditions.org</code> — a cheatsheet for driving conditions.</li>
|
||
<li><code>calc-me.flan</code>, <code>sand.flan</code>, <code>test/programs/</code> —
|
||
real programs that run.</li>
|
||
</ul>
|
||
|
||
</div>
|
||
|
||
<footer>
|
||
<p>Flan is a custard. This page describes the compiler on branch
|
||
<code>dev-loop</code>; where a document and the compiler disagree, the compiler is what
|
||
is written here.</p>
|
||
</footer>
|
||
|
||
</div>
|
||
</main>
|
||
|
||
<script>
|
||
// Tabs. The panels are plain markup and stay visible until this runs, so the
|
||
// page without a script is the one long document it was before. A link into a
|
||
// panel that is not showing switches to it first -- every #anchor on the page,
|
||
// and every link from outside, has to keep working.
|
||
(function () {
|
||
var main = document.querySelector("main");
|
||
var bar = document.querySelector(".tabs");
|
||
if (!main || !bar) return;
|
||
var tabs = Array.prototype.slice.call(bar.querySelectorAll("button"));
|
||
var panels = tabs.map(function (t) { return document.getElementById(t.dataset.panel); });
|
||
if (panels.some(function (p) { return !p; })) return; // markup moved; leave it long
|
||
main.classList.add("tabbed");
|
||
|
||
function show(i, focus) {
|
||
tabs.forEach(function (t, j) {
|
||
t.setAttribute("aria-selected", j === i ? "true" : "false");
|
||
panels[j].hidden = j !== i;
|
||
});
|
||
if (focus) tabs[i].focus();
|
||
}
|
||
|
||
function panelOf(id) {
|
||
var el = id && document.getElementById(id);
|
||
while (el && el !== document.body) {
|
||
if (el.classList && el.classList.contains("panel")) return el.id;
|
||
el = el.parentElement;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
function toHash() {
|
||
var want = panelOf(location.hash.slice(1));
|
||
if (!want) return false;
|
||
var i = panels.findIndex(function (p) { return p.id === want; });
|
||
if (i < 0) return false;
|
||
show(i);
|
||
var t = document.getElementById(location.hash.slice(1));
|
||
if (t) t.scrollIntoView();
|
||
return true;
|
||
}
|
||
|
||
tabs.forEach(function (t, i) {
|
||
t.addEventListener("click", function () { show(i); });
|
||
// Left and right move between tabs, which is what a tablist is expected
|
||
// to do once it says it is one.
|
||
t.addEventListener("keydown", function (e) {
|
||
var d = e.key === "ArrowRight" ? 1 : e.key === "ArrowLeft" ? -1 : 0;
|
||
if (!d) return;
|
||
e.preventDefault();
|
||
show((i + d + tabs.length) % tabs.length, true);
|
||
});
|
||
});
|
||
|
||
window.addEventListener("hashchange", toHash);
|
||
if (!toHash()) show(0);
|
||
})();
|
||
</script>
|
||
|
||
<script>
|
||
// A small hand-written highlighter for the Flan blocks. One pass, no library.
|
||
(function () {
|
||
var FORMS = new Set(("defn defstruct defenum defunion defconst defvar defalias " +
|
||
"declare declare-c import package let if when unless cond do and or not while " +
|
||
"until dotimes match set return some try defer signal error handler-bind " +
|
||
"restart-case invoke-restart fn quote defmacro gensym").split(" "));
|
||
// Capitalised names are types; these are the ones that are not capitalised.
|
||
var TYPES = new Set(("i8 i16 i32 i64 u8 u16 u32 u64 f32 f64 bool string").split(" "));
|
||
var TOKEN = /(;[^\n]*)|("(?:\\.|[^"\\])*")|(\\[A-Za-z0-9]+)|(:[A-Za-z][\w?!*<>=+-]*)|(\b0[xX][0-9a-fA-F]+\b|\b\d[\d.]*\b)|([A-Za-z][\w*?!<>=./+-]*)/g;
|
||
function esc(s) {
|
||
return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
|
||
}
|
||
document.querySelectorAll("pre > code").forEach(function (el) {
|
||
var lang = el.className;
|
||
if (lang && lang !== "flan") return; // sh, c and llvm blocks are left alone
|
||
el.innerHTML = esc(el.textContent).replace(TOKEN,
|
||
function (m, comment, str, chr, kw, num, word) {
|
||
if (comment) return '<span class="c">' + m + "</span>";
|
||
if (str) return '<span class="s">' + m + "</span>";
|
||
if (chr) return '<span class="s">' + m + "</span>";
|
||
if (kw) return '<span class="k">' + m + "</span>";
|
||
if (num) return '<span class="n">' + m + "</span>";
|
||
if (word) {
|
||
if (FORMS.has(word)) return '<span class="f">' + m + "</span>";
|
||
if (TYPES.has(word) || /^[A-Z]/.test(word))
|
||
return '<span class="t">' + m + "</span>";
|
||
}
|
||
return m;
|
||
});
|
||
});
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html>
|