Design notes
This page explains why the language is the way it is. It covers the choices behind the syntax, how pointers work, and how fast archec is. Read it when you wonder why something is written one way and not another.
One spelling for each thing#
Each thing has one standard spelling. Older spellings still parse, and
archec vet points them out. Save this as old.arche:
message PING "Ping" { field seq: uint8 }
component Sensor "Sensor" {
port data "Data": data out
states {
initial Idle
state Idle
}
}
component Logger "Logger" {
in data: data receives [PING]
}
system Bench "Bench" {
part sensor: Sensor
part logger: Logger
sensor.data -> logger.data
}archec vet old.arche
old.arche:4:3 hint Short form: `out data: data "Data"` — the direction is the keyword [long-form]
old.arche:7:5 hint `initial Idle` says nothing: a state machine starts in its first state [long-form]
old.arche:13:26 hint Short form: `receives PING` [long-form]
3 style finding(s) — `archec fmt --write` fixes the layout ones
archec fmt --simplify --write old.arche rewrites the file in the short forms
(out data: data "Data", no initial, receives PING). The Arche project
that archec build writes stays byte-for-byte the same.
The older spellings include:
port x "N": t outandout x "N": t;body ```…```;- lists in brackets,
[A, B]; initial X;: type { carries [M] };main "…"anddo "…";- two properties on one line without
;.
Each one is a long-form or same-line hint, with a quick fix in the editor.
Pointers#
*T is a pointer to a T. C-style T* also works, and so do **T, *void
and arrays of pointers (*T[4]). A pointer type works wherever a type does:
variables, struct and message fields, function arguments and results,
constants, memory blocks.
- A pointer is
pointer-sizebytes:project { pointer-size 8 }. The default is 4. - It holds an address: an integer, a constant or
nil. Anything else is an error (pointer-value). - Arche has no pointer type. So each pointer type becomes a catalog entry in
data-types.yaml. For exampleptr_Node, named*Node, is an unsigned integer as wide as an address, with unitaddress. - In the class diagram, a pointer field to a structure is an
association. - A pointer in a message payload is flagged (
pointer-on-wire): an address means nothing to the receiver.
Choices in the language#
Contextual keywords. The lexer only produces identifiers. Meaning comes from position, so
state,typeorportcan still be used as names.Line-sensitive properties. A property's values start on its own line (
priority high). After a comma they may continue on the next line.- So properties can sit one per line with no separators. On one line,
;separates them. - So the formatter only re-indents: it never moves a token.
- The one exception: a
block opened at the end of a header (`fn fpython`) has its body indented one level under that header. The code does not change, because a block's common indentation is removed when it is read.
- So properties can sit one per line with no separators. On one line,
Python where Python goes. Some places take Python as it is, to the end of the line:
do,expectandsetupin test plans,doin stimuli, and a transition's/ action. Brackets must balance; a;or the block's}ends the code. You write no quotes and no\"escapes, and the linter can read the names.Identifiers may contain
-(REQ-BRK-001,can-fd), as Arche ids do. Write subtraction with spaces:a - b. IfMAXis a constant andMAX-1names nothing: the linter reportshyphen-minus, with the fixMAX - 1.Structure apart from layout.
canvas System { … }holds the canvas positions. So the system reads as what is connected to what, and moving a block on the canvas does not touch it.One table describes the language (
src/spec.ts). The parser's contexts, the linter's property checks, completion, hover anddocs/patterns.mdall come from it.One way to write each thing (
src/canonical.ts).- Every declaration has one standard keyword.
- Multi-word keywords take a hyphen:
port-type,test-plan,use-case,failure-mode. - A word means one thing.
busis not a port type: a bus is a component withkind bus.processis an OS process in a deployment; a workflow is aworkflow.modeis anoperating-mode, not a state. - A pseudo-state is
pseudo choice;kindis for the catalog. - A requirement's provenance is
origin;sourceis where code lives. - Fields are
attr key = value, likeprop key = value. - A private function is
private fn. extendsgoes in the header.- Lists have no brackets.
- Values are lower case (
complexity medium). - A unit is written as it is (
unit m/s²,unit °C). It is quoted only when it has a space. processoranddevicearecomponent. What makes a block hardware iskind processor(orcores).
Older spellings are still read, and they build the same project. Each one is an
alias-keywordhint, andarchec fmt --simplifyrewrites it.
Performance#
node tools/bench/bench.js times archec on two models:
- a real project of 69 files (1.7 MB), read from the folder
ANTENNA_DIRnames; - a model ten times its size (681 files, 17 MB), made from it by
tools/bench/synth.js: the project plus nine copies with every declaration renamed.
It times load, check and emit inside one process; archec check and
archec build as commands; and the language server over stdio.
The table is in ms, on an Apple M4 Max shared with other work. The numbers move by 10–20 % from one run to the next. "Before" is commit 76ea8f2, before this work.
| 1× before | 1× after | 10× before | 10× after | |
|---|---|---|---|---|
| load + check, warm | 230 | 122 | 3024 | 1248 |
| one-file edit, check again (end of the file / its middle) | 230 | 55 / 70 | 3133 | 541 / 664 |
| whole compile (emit, schema, rules), warm | 401 | 277 | 7762 | 5651 |
archec check |
750 | 621 | 8407 | 6204 |
archec build |
1316 | 759 | 12495 | 7136 |
| editor: open → first diagnostics | 725 | 302 | 8124 | 1733 |
| editor: keystroke → diagnostics | 449 | 174 | 3197 | 831 |
What made the difference:
- Work that grew faster than the model. Four things were slow on a large
model. Check is now 2.5× faster on the 10× model, and load 2× faster.
- The ports that provide an interface were found by walking the whole model, once per interface.
- The long forms parsed every file a second time.
defaultswere searched for every node.- The lexer tested each character with a regular expression.
- An incremental compile (
src/incremental.ts,Session).- The check runs in pieces: each top-level declaration, and each file's long forms.
- archec records what each piece reads: the names it looked up and what they gave, the declarations it reached, the files it looked into, and the namespaces it listed.
- After an edit, a piece is not run again when its own declaration and everything it read are unchanged. Its diagnostics and references are reused, in their place.
- Some edits change what loading does across files: the includes, a package, the project, translations, means, generics, or a .py file. After those, everything is checked again.
- The tokens of unchanged files are kept too.
test/incremental.test.jschecks it. After random single-file edits of every example, it compares the result with a compile from scratch. The diagnostics must be the same, in the same order, and the project the same byte for byte.ARCHE_INC_SEEDS=150runs 22 000 edits.
- The language server.
- It compiles each project with a Session.
- It reads a file from disk again only when the file's size or time changes.
- It answers "what is here", references, rename, symbols and semantic colours from an index of each program.
- It runs the full compile (emit, schema, rules) in a worker thread, so a keystroke's check never waits for it.
- The pause before a keystroke's check follows how long the last check took (50–200 ms).
- Arche's rule engine. It is bundled in
vendor/arche.js, andarchec checkand the full compile run it. It copied every project constant into each subject's scope for each rule. It also counted each element's traces by going through all of them. Now it looks the constants up, and counts the traces once (arche/frontend/src/rules.ts).archec checkon the 10× model went from 6.7 s to 3.4 s, with the same output byte for byte.
Limits#
- Loading (about 250 ms on the 10× model) and the whole-project checks (about 150 ms) still run in full on every edit.
- The CLI has no disk cache. Most of its time goes to the emit, which an edit changes anyway.