Skip to content

Say what else is in the file, and offer the running example #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
onatozmenn merged 1 commit into from
Aug 7, 2026
Merged

Say what else is in the file, and offer the running example #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Concretely, that rules out a few things that would otherwise be tempting:
pages the compiler generates rather than a list maintained here.
- No examples written here. The playground's are the compiler's corpus at the
pinned tag, and the summary under each one is the comment at the top of the
file. Which thirteen of them the picker offers is a choice made here, and it is
file. Which fourteen of them the picker offers is a choice made here, and it is
the only one: choosing what to show is not writing it, and every file is
still served. The landing page's program is the exception, and it is short
and its refusal was still produced by running it.
Expand Down Expand Up @@ -98,11 +98,11 @@ records the capabilities they asked for. That leaves exactly one example this
page can start, and Run is off for the other twenty-eight with the reason
beside it, rather than letting somebody press it and be refused.

The picker shows thirteen of the twenty-nine, and that list is in
The picker shows fourteen of the twenty-nine, and that list is in
`tools/artifact.mjs` because both tools need it. The corpus is not a menu:
about half of it is one language feature at a time, written so the compiler's
own tests have something to read, and a visitor scrolling past `sink`, `names`
and `diverge` is being shown the inside of a test suite. The other sixteen stay
and `diverge` is being shown the inside of a test suite. The other fifteen stay
here, still asked about, still reachable by name.

Forgetting that step is caught rather than shipped. `tools/check.mjs` asks the
Expand Down
4 changes: 2 additions & 2 deletions examples/index.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@
},
{
"file": "proven.deed",
"shown": 12,
"shown": 13,
"summary": "The Proven tier, which is the part of this language that is supposed to be interesting.",
"runs": false,
"needs": [],
Expand Down Expand Up @@ -223,7 +223,7 @@
},
{
"file": "transfer.deed",
"shown": -1,
"shown": 12,
"summary": "The running example, and two of the fourteen design documents work through it: design/02-syntax.md and design/03-effects.md.",
"runs": false,
"needs": [],
Expand Down
108 changes: 106 additions & 2 deletions install/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,9 @@ <h2>A function can only do what its signature admits to.</h2>
<main>
<h1>Install</h1>
<p class="lede">
One file. The compiler, the formatter, the test runner and the
language server are all in it, and there is nothing else to install.
One file. The compiler, the test runner, the formatter, the
WebAssembly backend, the language server, the debugger and the agent
server are all in it, and there is nothing else to install.
</p>

<!--
Expand Down Expand Up @@ -194,6 +195,109 @@ <h2>A first program</h2>
browser tab, so you can try things there without any of this.
</p>

<!--
The lede claims a list, and this is it. Every line here is a
shortened `deed --help`, which is the binary describing itself; the
page named two of these and showed one of them for four releases,
which is a page that undersells the file it is telling you to
download.
-->
<h2>What else is in it</h2>
<p>
The same file with a different first word each time. None of them
needs anything else on the machine, and
<code>deed --help</code> is the longer version of this table.
</p>
<table class="files">
<thead>
<tr>
<th scope="col">Command</th>
<th scope="col">What it is</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>deed check</code></td>
<td>The compiler. Silence is the answer.</td>
</tr>
<tr>
<td><code>deed test</code></td>
<td>
The test blocks, and the properties a contract generates. It
refuses to run anything that does not check.
</td>
</tr>
<tr>
<td><code>deed run</code></td>
<td>
Calls <code>main</code>, handing it the one
<code>System</code> capability there is.
</td>
</tr>
<tr>
<td><code>deed build</code></td>
<td>
Compiles to WebAssembly. With <code>--component</code>, writes
the <code>.wit</code> world the effect rows add up to, which is
<a href="../one-clause/">the one clause</a> page.
</td>
</tr>
<tr>
<td><code>deed doc</code></td>
<td>
A module's API reference, as Markdown. No visibility modifiers
here, so there is nothing to decide about what belongs on it.
</td>
</tr>
<tr>
<td><code>deed fmt</code></td>
<td>One canonical form, and no options for the output.</td>
</tr>
<tr>
<td><code>deed fix</code></td>
<td>
Applies the repairs that are certain and leaves the guesses
alone.
</td>
</tr>
<tr>
<td><code>deed explain</code></td>
<td>
The page for one diagnostic code.
<a href="../errors/">Every code has one.</a>
</td>
</tr>
<tr>
<td><code>deed lsp</code></td>
<td>A language server, for an editor to start rather than you.</td>
</tr>
<tr>
<td><code>deed debug</code></td>
<td>
A debug adapter: breakpoints, stepping, and the stack and
bindings of every active call.
</td>
</tr>
<tr>
<td><code>deed mcp</code></td>
<td>
A Model Context Protocol server, so an agent can ask the
compiler the questions an editor asks.
</td>
</tr>
</tbody>
</table>
<p>
The last one is worth a second sentence, because the argument this
language is built on is that most code is no longer typed out by a
person. <code>deed mcp</code> holds no capability: a program arrives
as text and the answer leaves as text, and nothing it runs can reach
a file. What it hands back is not only the diagnostics but which tier
each obligation landed in, so the thing writing the code can see the
difference between a contract that was proved and one that was left
to a runtime check.
</p>

<h2 id="source">From source</h2>
<p>Needs Rust 1.85 or newer, and nothing else:</p>
<pre class="code"><code>$ git clone https://github.com/deed-lang/deed
Expand Down
9 changes: 8 additions & 1 deletion tools/artifact.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,18 @@ import { readFile } from "node:fs/promises";
// one language feature at a time, written so the compiler's own tests have
// something to read, and a visitor scrolling past `sink`, `names` and
// `diverge` is being shown the inside of a test suite. So the picker is
// thirteen programs a person would recognise, and the rest stay on disk, still
// fourteen programs a person would recognise, and the rest stay on disk, still
// asked about here and still reachable by name.
//
// `hello` is first because it is the only one this page can start. The others
// have tests, which is the button that works for them.
//
// `transfer` is late rather than absent, which it was for four releases. It is
// the program every design document works through and the one the README
// opens with, and it is not a feature written down on its own: it is a ledger
// with an effect, a handler, a contract and a refinement in it. Leaving it out
// while offering `counter` was an oversight rather than a judgement.
//
// It lives beside the code that asks the compiler because both tools need it:
// one writes the order into the index and the other checks it is still there.
export const SHOWN = [
Expand All @@ -34,6 +40,7 @@ export const SHOWN = [
"logs.deed",
"todo.deed",
"tasks.deed",
"transfer.deed",
"proven.deed",
];

Expand Down