Bien écrire en Arche
Cette page explique comment écrire un modèle qui se lit comme tous les autres. Le langage (spec.md) dit ce qui est permis. Cette page dit ce qui est bien.
L’essentiel est fait pour vous. archec fmt --write écrit la mise en forme, et
archec vet signale le reste. Chaque section ci-dessous correspond à un code de
vet, et archec explain <code> affiche cette section.
Un premier essai#
Ce modèle utilise un ancien mot-clé (msg), met deux éléments sur une même
ligne, et nomme une part avec la mauvaise casse (Desk) :
msg GO: bool
component Lamp "Lamp" {
in cmd: can receives GO; kind ecu
}
system Room "Room" {
part Desk: Lamp
}
Enregistrez-le sous main.arche. Laissez d’abord archec fmt écrire la mise en
forme :
archec fmt --write main.arche
formatted main.arche
Le fichier contient maintenant message GO: bool, et kind ecu est sur sa
propre ligne. Demandez ensuite le reste à archec vet :
archec vet main.arche
main.arche:9:8 hint 'Desk' is a part: `desk` (rename it in the editor — every use follows) [naming]
1 style finding(s) — `archec fmt --write` fixes the layout ones
archec vet renvoie le code 1 quand il a une remarque, et le code 0 quand il
affiche ✓ vet: nothing to say.
La forme d’un projet#
- Un dossier par projet, avec le fichier principal à sa racine (
main.arche). Puis un dossier par domaine du système :models/;spec/: les exigences et les fonctions ;verification/: les plans de test et les scénarios ;app/: ce que montre l’application Arche.
- La structure dans les
.arche, le comportement dans les.py, les traductions à part.- Un fichier de modèle dit ce qu’est le système.
- Son Python vit à côté.
archec fmt --extract-codel’y déplace. - Les textes dans une seconde langue vivent dans
translations/<lang>.arche.archec refactor translations --extract enles y déplace.
- Écrivez d’abord le cœur : composants, ports, liens, messages, exigences, plans de test. Ajoutez les autres jeux quand vous en avez besoin : déploiement, analyse fonctionnelle, sûreté et sécurité, l’application.
long-form#
Il y a une seule façon d’écrire chaque chose. Une forme plus ancienne ou plus
longue se lit encore, mais archec fmt écrit la forme standard :
message, et nonmsg;out tx: can, et nonport tx: can out;unit m/s, et nonunit "m/s".
bad: msg GO: bool good: message GO: bool
bad: port tx "TX": can out good: out tx: can "TX"
same-line#
Un élément par ligne. N’utilisez ; entre des éléments qu’à l’intérieur d’un
bloc écrit sur une seule ligne :
bad: kind ecu; layer physical good: kind ecu
tags safety layer physical
tags safety
fine: widget title { type text; at [0, 0, 12, 1] }
property-order#
Écrivez les propriétés d’un élément dans le même ordre dans chaque fichier. L’œil sait alors où regarder. L’ordre est le suivant :
- ce qu’il est :
description,text,objective; - comment il est classé :
kind,layer,tags,status,priority… ; - son type :
provides,sends,unit… ; - le reste ;
- ses traces :
satisfies,verifies,derives… ; - sa place sur le canevas :
at,size.
archec fmt les remet dans cet ordre.
property-group#
Quand trois propriétés ou plus vont ensemble, écrivez-les sous forme de groupe :
timing { latency 2ms; jitter 100us; bitrate 1Mbps }. Le groupe signifie la
même chose que les trois lignes. Les groupes sont timing, delivery,
compute, physical et errors.
declaration-set#
Les déclarations de l’application Arche vivent dans app/*.arche, à part du
modèle. Ce sont les pages, les panneaux, les widgets, les stories, les
benchmarks et le menu. Ainsi, un fichier de modèle ne contient que le système.
naming#
La casse d’un nom dit ce qu’il désigne, comme en Go :
| Quoi | Casse | Exemple |
|---|---|---|
| une définition, un système, un type, une interface | PascalCase |
BrakeEcu, Car, Speed |
| une part, un port, une fonction, une variable | snake_case |
brakes, can0, regulate, target_speed |
| un message, une constante, un littéral d’énumération | SCREAMING_CASE |
BRAKE_CMD, MAX_SPEED, AUTONOMOUS |
| une exigence, un plan de test, un cas | tel que son document l’écrit | REQ-BRK-001, TP-AEB, TC-AEB-01 |
Un nom importé garde son identifiant Arche grâce à as, par exemple
component flash_memory "FLASH" as c-1793752253957. Pour renommer, utilisez
l’éditeur (F2) : chaque utilisation suit.
code-in-model#
Un bloc Python de plus de quelques lignes, c’est du comportement. Il se lit
mieux dans le fichier .py placé à côté du modèle.
archec fmt --extract-code --write l’y déplace, et la fonction y reste liée.
arche-body#
Certains corps Python ne font que ce que fait le langage d’action : if,
goto, send, return, des affectations, des comparaisons, wait, log, et
des appels aux fonctions de la part. Un tel corps se lit mieux en
corps ```arche. archec le vérifie alors, et le traduit en C, en Rust et en
Go, et pas seulement en Python.
Le correctif rapide Convert to arche body l’écrit, tout comme
archec fix --only arche-body. Un corps qui en fait plus reste en Python : une
liste, une bibliothèque, un nom que le modèle ne déclare pas.
Petites choses#
- Un libellé, c’est ce que les gens lisent. Écrivez-en un sur chaque
déclaration qu’un lecteur rencontre :
component BrakeEcu "Brake ECU". - Écrivez une garde entre crochets :
Idle -> Run on GO [speed > 0]. - Écrivez une trace là où elle part :
satisfies REQ-1sur la part,verifies REQ-1sur le cas.archec refactor move-tracesdéplace les traces écrites à part. - Les cas qui ne diffèrent que par leurs valeurs vont dans une seule table
cases. - archec signale un texte invérifiable, comme « as fast as possible » ou « TBD »
(
vague-word). Donnez le nombre, ou marquez l’exigencetbc.