Explanation › Design notes

Explanation

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
}
Diagram: Bench
What archec draws from this code: Bench
Try it
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 out and out x "N": t;
  • body ```…``` ;
  • lists in brackets, [A, B];
  • initial X;
  • : type { carries [M] };
  • main "…" and do "…";
  • 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-size bytes: 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 example ptr_Node, named *Node, is an unsigned integer as wide as an address, with unit address.
  • 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, type or port can 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.
  • Python where Python goes. Some places take Python as it is, to the end of the line: do, expect and setup in test plans, do in 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. If MAX is a constant and MAX-1 names nothing: the linter reports hyphen-minus, with the fix MAX - 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 and docs/patterns.md all 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. bus is not a port type: a bus is a component with kind bus. process is an OS process in a deployment; a workflow is a workflow. mode is an operating-mode, not a state.
    • A pseudo-state is pseudo choice; kind is for the catalog.
    • A requirement's provenance is origin; source is where code lives.
    • Fields are attr key = value, like prop key = value.
    • A private function is private fn.
    • extends goes 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.
    • processor and device are component. What makes a block hardware is kind processor (or cores).

    Older spellings are still read, and they build the same project. Each one is an alias-keyword hint, and archec fmt --simplify rewrites 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_DIR names;
  • 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.
    • defaults were 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.js checks 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=150 runs 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, and archec check and 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 check on 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.