Référence › Référence du langage › Basics

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

Basics

The rules every arche-lang file follows, before any declaration.

On this page: The sets · Lexical rules · LaTeX · Short forms · Types and pointers · Python in .py files · Built-in vocabulary

The sets#

The declarations come in sets, like Go's language and its packages: the model is what every model is written with; the others are for a purpose. Each declaration below says its set. What to learn first is the 1.0 core (docs/core.md), a part of these sets: it is what level simple offers.

Set What it is for Declarations
The model What every model is written with: the project and its files, the catalogs, data and messages, requirements, components with their ports, functions, variables and state machines, links, traces, and test plans. project, package, include, kind, layer, tag, color, port-type, wire, interface, contract, type, enum, struct, field, const, message, requirement, verify, defaults, system, component, port, handler, fn, var, memory, states, state, link, trace, test-plan, case, cases, step
Deployment Where the parts run: processors and their cores, containers, binaries, processes, threads and interrupts, the bus each link takes, latency chains, and the watchdogs a part keeps. core, deployment, container, binary, process, thread, isr, route, chain, watchdog, allocator, place
Functional analysis & scenarios Who uses the system and what for, its functions and their flows, the events its machines react to, operating modes, scenarios and their sequences, the simulation. actor, mission, event, use-case, system-function, function-flow, function-chain, step, edge, operating-mode, deliverable, means, icd, scenario, participant, sequence, alt, when, ref, workflow, simulation, stimulus, keyframe, canvas
Safety, security & design space Hazards and safety goals, failure modes and fault trees, the threat analysis, design decisions, variants, parameters and studies, viewpoints and the project's rules. hazard, safety-goal, failure-mode, gate, control-action, uca, loss-scenario, asset, damage-scenario, threat, attack-path, security-goal, decision, variant, parameter, study, viewpoint, rule
Product UI The user interface of the product: its device, screens, layouts and elements, bound to the model (the words inside ui { } are words only there). ui
The Arche app How the Arche app shows the project: its pages and tabs, panels and widgets, stories, benchmarks, visuals, tables, the menu and plugins. Kept in app/*.arche. app, page, tab, panel, widget, story, step, benchmark, run, visual, animation, table, column, menu, entry, plugin
Project tooling Libraries and their versions, translations, units, property definitions, tag groups, and files written as they are. library, translations, file, raw, unit, property, tag-group, generator, importer, exporter, option

Lexical rules#

Element Syntax
Line comment // …
Block comment /* … */
Doc comment (becomes the description of the next declaration) /// …
Identifier letters, digits, _; - allowed inside (REQ-BRK-001, f-boot) — write subtraction with spaces
Number 42, 3.14, 1e-3, 0xFF, 0b1010, 1_000_000
Quantity number + unit, no space: 5ms, 100MHz, 3.3V, 2kg. Time units (ps, ns, us, µs, ms, s, min, h) are durations
String "…" with \n \t \" \\; other backslashes are kept (LaTeX-friendly: "$\frac{a}{b}$")
Multi-line string """…""" (common indentation removed)
Code block ```python … ```, ```latex … ```, ```yaml … ```
Lists, records, ranges [a, b], {x: 1, y: 2}, 0..250, 1..*
Separators Newlines end a property; on one line, ; separates them ({ at 1, 2; satisfies R } — the linter asks for it). A property's values start on its line; after a , they may continue on the next

LaTeX#

Any description, requirement text, rationale or objective may contain inline math $…$ or display math $$…$$. A math property (or a ```latex / ```math block) holds raw LaTeX. The math is kept as written in the generated YAML; archec doc main.arche -o spec.tex typesets it in a complete LaTeX specification. \$ writes a literal dollar.

requirement REQ-BRK-001 "Stopping distance" {
  text "The vehicle shall stop within $d \le \frac{v^2}{2\mu g}$ on dry asphalt."
  math ```latex
  \mu \ge 0.7
  ```
}

Short forms#

Write the short form. The long one is still accepted, but the linter marks each one (long-form, a hint with its quick fix) and archec fmt --simplify --write rewrites them all without changing the generated project — so a reader only ever has to know one spelling.

Short Long Rule
out tx: can "CAN" sends A, B port tx "CAN": can out sends [A, B] A port starts with its direction: in, out or inout
out tx: can "CAN", part cam: Camera "Front" out tx "CAN": can The type comes right after the name, the display name after the type
purpose "Fuses the sensors" main "Fuses the sensors" What a component is for — main is easy to read as fn main
do send(hmi.bus, GO(True)), expect adcu.state == 'Ready' do "send(hmi.bus, GO(True))", expect "adcu.state == \"Ready\"" Test steps and stimuli take Python as it is, one assertion per expect; the linter checks the messages and states it names
A -> B on e / log('x') A -> B on e / "log('x')" A transition action is Python as it is
fn f(x: int32) ```python …``` fn f(x: int32) { body ```python …``` } A code fence right after a function is its body; inside a block, a bare fence is too
tags safety, asil-d tags [safety, asil-d] Lists of names need no brackets
states { state Off; state On; … } states { initial Off; state Off; … } The first state is the initial one, unless initial says otherwise
a.tx -> b.rx "Bus" a.tx -> b.rx "Bus" : can { carries [A, B] } A link's type comes from its ports, and what it carries from what the source port sends (and the target accepts)
component Sensor {
  out data: can "Samples" sends SAMPLE
  in cfg: can receives CONFIG
  fn main ```python
    while True:
        await wait(ms(10))
        send(self.data, SAMPLE(value=1))
  ```
}
system Rig { part s: Sensor; part c: Controller; s.data -> c.data_in "Samples" }

Types and pointers#

Built-in types: bool, uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float64, char, byte, string, bytes, duration, timestamp, any, void — plus every type, enum and struct you declare. A type may be an array (uint8[16], Sample[]) and a pointer:

Type Meaning
*T or T* an address of a T; pointer-size bytes (project property, default 4)
**T, char** a pointer to a pointer
*void an untyped address
*T[4] an array of four pointers

A pointer is initialised with an address, a constant or nil. In the Arche project it becomes a catalog entry ptr_T (an unsigned integer as wide as an address, unit address); a pointer field to a structure is an association in the class diagram. A pointer in a message payload is flagged: an address means nothing in the receiver's memory.

project "Firmware" { pointer-size 4 }
struct Block { size: uint32; next: *Block; data: uint8* }
component Allocator {
  var free_list: *Block = nil
  memory DMA_SRC @ 0x4000_0010 : *void rw
  fn alloc(n: uint32) -> *Block ```python
    return self.free_list
  ```
}

Python in .py files#

Code longer than a few lines reads better in a .py file, with your editor's Python support. code "ctrl.py" on a component (or a system, or the project) names the file; in the model a function's name goes where a ``` block would. archec copies each body into the Arche project, so Arche runs exactly what the same code written inline would give (archec fmt --extract-code --write moves existing blocks out, and that is tested to change nothing).

In the model In the .py file Rule
fn main (no block) async def main(self): A fn with no block takes the def of the same name in the component's own file
fn add(a: int32, b: int32) def add(self, a, b): Parameters: self, then the fn's arguments, in order
on-enter enter_on def enter_on(self): Any code property takes the def it names: on-enter, on-exit, on-receive, on-write, body
Off -> On on GO / turn_on def turn_on(self, msg): A transition's action can name a def too
(nothing) def on_exit_On(self): Bound by its name: on_enter_<State>, on_exit_<State>, on_receive_<port>, on_write_<MEMORY>
project { code "shared.py" } def log_off(self): A file on the project or an enclosing system is shared: its defs bind only when named

A hook's parameters are the names Arche gives it, the ones you use: a port msg, message, port, value, prev, rise, fall and the fields of the messages it receives; a state from_, to; a memory block index, value, field, writer. Imports, constants and helper functions at the top of the file are copied into the bodies that use them — a copy per body, so a top-level name cannot keep state between calls: keep it on the component (var n in the model, self.n in Python). A def's docstring becomes the function's description. from arche import * is for the editor only: archec stubs (or the VS Code extension, on its own) writes a typed arche package in .arche/typings, in the folder of the main file, with Arche's helpers and the model's messages and constants. Nothing is written beside the .py files.

Code edited in the Arche app comes back with archec pull main.arche --write (into the def or ``` block it came from; a build will not overwrite it until it is pulled), and Arche's errors — "(Controller › Control loop, line 4)", a line of the copy — are mapped back to the source line by archec test, archec run and archec where (and the VS Code commands Run Tests and Go to Simulator Error…).

component ctrl "Controller" {
  code "ctrl.py"
  in sense: i2c receives SAMPLE { on-receive on_sense }
  fn main "Control loop"
  fn command(rpm: Rpm)
  states {
    state Off
    state On { on-enter enter_on }      // on-exit: def on_exit_On, by its name
  }
}
# ctrl.py
from arche import *

async def main(self):
    while True:
        await wait(PERIOD)
        await self.command(self.target)

def command(self, rpm):
    send(self.bus, SPEED_CMD(rpm=rpm))

def on_sense(self, msg):
    self.last = msg

def enter_on(self):
    log("on")

def on_exit_On(self):
    log("off")

Built-in vocabulary#

Types: bool, uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float64, char, byte, string, bytes, duration, timestamp, any, void. Arrays: T[n], T[].

Port types (no declaration needed): ethernet, spi, i2c, uart, can, usb, pcie, gpio, jtag, hdmi, rf, power, http, tcp, data, control, mil-std-1553, spacewire, lin, flexray, mipi, pwm, analog.

Trace kinds: satisfies, verifies, derives, refines, allocates, realizes, involves, deploys, traces.