Handlers : TypeScript, Python, le langage d’action
Un handler est une partie du comportement d’un modèle écrite sous forme de code :
le corps d’une fonction, le on-receive d’un port, le on-enter d’un état.
Vous l’écrivez en TypeScript, en Python ou dans le langage d’action
(```arche), qu’archec traduit. archec new écrit du TypeScript.
Un premier handler#
Enregistrez ceci sous main.arche. Le projet indique que ses handlers sont en
TypeScript. Le pinger envoie un PING numéroté toutes les 20 ms, et le ponger
journalise ceux qui suivent le premier.
project "Ping" {
handlers typescript
}
message PING { n: int32 }
component Pinger "Pinger" {
out tx: data sends PING
var sent: int32 = 0
states {
state Idle
state Busy {
on-enter ```ts
self.sent += 1
send(self.tx, PING({ n: self.sent }))
```
}
Idle -> Busy on "after 10ms"
Busy -> Idle on "after 10ms"
}
}
component Ponger "Ponger" {
in rx: data receives PING {
on-receive ```ts
if (msg.n > 1) log("got", msg.n)
```
}
}
system Desk {
part pinger: Pinger
part ponger: Ponger
pinger.tx -> ponger.rx
}Lancez-le dans le simulateur du navigateur :
$ archec sim main.arche --for 30ms
Ping — system Desk, 30.000 ms simulated
0.000 ms pinger: Idle
10.000 ms pinger: Idle → Busy
10.000 ms pinger.tx → ponger.rx PING {"n":1}
20.000 ms pinger: Busy → Idle
30.000 ms pinger: Idle → Busy
30.000 ms pinger.tx → ponger.rx PING {"n":2}
30.000 ms ponger: got 2
2 message(s), 4 state change(s)
at 30.000 ms: pinger Busy
Pour avoir les mêmes handlers en Python, convertissez-les :
$ archec convert-handlers main.arche --to python
2 bodies, 3 statements translated, 0 left as TODO(convert)
✓ main.arche
Le projet indique désormais handlers python, et le corps du ponger devient :
if n > 1:
log("got", n)
La suite de cette page est le contrat entre archec et le simulateur d’Arche. Les
deux côtés font ce qu’il dit. Pour tout ce qu’il ne dit pas, faites comme le
runtime Python (le arche_runtime.py d’Arche), avec les mêmes noms.
1. Dans quel langage est écrit un morceau de code#
En arche-lang, le langage se choisit à quatre niveaux :
- Le projet l’indique :
project { handlers typescript }, oupython, ouarche. - Un composant peut indiquer le sien :
component Legacy { handlers python }. Sinon, un composant prend, dans cet ordre :- le langage de sa définition ;
- le langage du composant qui le contient ;
- le langage de ses fichiers
code(code "ctrl.ts"est du TypeScript,code "ctrl.py"du Python) ; - le langage du projet.
- Un bloc indique le sien :
```ts,```python,```arche. Un bloc```nu est dans le langage du composant. - Un projet sans
handlersgarde le langage de son code. Du Python quelque part (un fichier.py, un bloc```pythonou un bloc nu) le met enpython. Sinon, il est entypescript.
archec new écrit handlers typescript. Utilisez
archec new --handlers python|arche pour les autres.
Dans le projet Arche :
simulation.yamlindique le langage du projet :behavioral: { language: typescript | python }. En son absence, le langage estpython, si bien que tous les projets existants continuent de fonctionner. archec l’écrit quand le projet indiquehandlers, ou quand le projet contient du code et que ce code est du TypeScript.- Le fichier de code d’un fichier de modèle décide du langage du code de ce
fichier :
code: "rfic.ts"est du TypeScript,code: "rfic.py"du Python. - Le code en ligne suit le fichier de code du composant s’il en a un, sinon le langage du projet. Le code en ligne, ce sont les corps d’activation, les handlers, les actions d’état et les gardes écrites sous forme de code.
Le langage d’action est traduit :
- pour Arche, dans le langage du projet. C’est du TypeScript, ou du Python dans
un projet
handlers python.handlers archedonne du TypeScript. - pour le firmware, en C, Rust ou Go, comme avant.
Un appel vers une autre part est traduit lui aussi. Par exemple,
brake.apply(2.5) passe par un port qui requiert une interface dotée de cette
opération. Il devient ce qu’un handler écrirait : await component("brk").apply(2.5),
pour la part à l’autre bout du lien
(la spécification).
archec copie chaque corps dans le projet Arche : Arche exécute donc un seul
langage pour tout le projet. Une fonction code "x.ts" devient le corps en
ligne qu’elle serait si on l’écrivait ainsi. Un bloc dans l’autre langage est
signalé (handlers-language) : archec sim l’exécute, mais Arche ne le ferait
pas.
2. À quoi ressemble le code TypeScript#
La source est en TypeScript. Les deux côtés retirent les types et exécutent le JavaScript. archec les retire lui-même (src/tscode.ts) : il n’y a rien à installer. Arche utilise un petit transpileur dans la page. Rien n’est vérifié par le typage avant l’exécution.
Un fichier de code reflète un fichier .py trait pour trait, avec les mêmes
noms de fonctions :
import { send, reply, goto, wait, ms, warn, u8 } from "arche" // optional: the names are global anyway
import type { Rfic, SPI_FRAME } from "arche" // archec stubs: the model's types
export async function rfic_on_receive_spi(self: Rfic, msg: Rfic.Msg) {
if (msg.name !== "SPI_FRAME" || (msg.cs !== self.cs_index && msg.cs !== RFIC_BROADCAST)) return
self.frames += 1
if (msg.cmd === 0) reply(SPI_FRAME({ cs: msg.cs, cmd: 0, addr: msg.addr, data: await self.readRegister(msg.addr) }))
else await self.writeRegister(msg.addr, msg.data)
}
self. Le premier paramètre estself, comme en Python.self.xlit et écrit une variable.self.STATUS.stateest l’état d’un port.self.mem[...]est la mémoire.await self.f(a)appelle une fonction du composant.- Seul le propriétaire écrit ses variables. C’est la même règle qu’en Python.
- Un message reçu est une valeur, pas des noms nus.
- Python met les champs d’un message dans la portée sous forme de noms nus,
et passe son nom dans
message. - TypeScript passe un seul argument,
msg. C’est un objet qui contient les champs par leur nom et lenamedu message :{ name: "SPI_FRAME", cs, cmd, addr, data }. - Dans le code en ligne,
msgest dans la portée.messagel’est aussi : c’est le nom du message (une chaîne), pour le code repris de Python.
- Python met les champs d’un message dans la portée sous forme de noms nus,
et passe son nom dans
- Le code en ligne est le corps d’une fonction
async.selfest dans la portée, etmsgaussi quand un message l’a déclenché :self.count += 1; await goto("Run"). - Les constructeurs de messages prennent un seul objet :
SPI_FRAME({ cs: 1, cmd: 0 }). Cela remplace les arguments nommés de Python. - Les littéraux d’énumération et les constantes sont des noms globaux, comme en Python.
Dans un modèle, un fichier code "ctrl.ts" se relie au modèle comme un fichier
.py. Chaque élément prend la fonction qui porte son nom conventionnel :
| Élément | Fonction dans le fichier |
|---|---|
fn main |
main |
un état On |
on_enter_On et on_exit_On |
un port rx |
on_receive_rx |
une mémoire M |
on_write_M |
on-enter name |
la fonction nommée |
Les paramètres d’une fonction sont self et les arguments du fn. Pour le hook
d’un message, ce sont self, msg. Les autres paramètres sont signalés
(py-params).
Les constantes, types et fonctions utilitaires en tête de fichier sont copiés
dans chaque corps qui les utilise. Les imports ne servent qu’à l’éditeur et sont
supprimés. Seuls "arche" et "./arche" peuvent être importés : les deux désignent
le arche.d.ts du modèle.
3. L’API#
L’API est un ensemble de noms globaux. Ce sont les mêmes que dans
arche_runtime.py.
Les attentes s’écrivent avec await, comme en Python :
wait(d), wait_until(test, timeout?), clock(n?), recv(port, timeout?),
select(...ports) / select([ports], timeout),
call(port, msg, to?, timeout?), goto(state), put/get/take(port, …),
lock(port, timeout?), wait_bits(port, bits, { all, clear, timeout }),
stream_write/stream_read, compute(d).
Les appels immédiats s’écrivent sans await :
- messages et ports :
send(port, msg, to?),reply(msg),give,unlock,set_bits,clear_bits,queued,start_timer,stop_timer,pulse(signal, width?),at(address),message(name),component(name); - sortie :
log(...a),warn(...a),print(...a)(vers la trace),fail(msg?); - temps et hasard :
now(),rand(),randint(lo, hi),randn(mu?, sigma?). Le moteur fixe leur graine. N’utilisez jamaisMath.randomniDate; - durées :
ns/us/ms/sec(x),to_ms/to_us/to_s(t),fmt(t); - bits et entiers :
bits(v, hi, lo?),bit(v, n),setbits(v, hi, lo, x),u8/u16/u32/u64/i8/i16/i32/i64(n).
Le with locked(p): de Python s’écrit await lock(p); try { … } finally { unlock(p) }.
Math.* est autorisé, sauf Math.random.
Les règles sont les mêmes qu’en Python :
- Déterminisme. Revenir en arrière réexécute le code, qui doit donner le même résultat.
- Boucles infinies. Les tours de boucle sont comptés. Au-delà de la même limite, c’est une erreur.
4. Où il s’exécute, et les types#
Arche l’exécute dans un
JsRuntime(Lang = 'python' | 'typescript'), dans un Web Worker, sans DOM ni réseau. Le moteur gère le temps et l’état. Il utilise le même protocole d’appels vers l’hôte que le pont Python. Pyodide n’est chargé que si le projet contient du code Python.archec sim(src/websim.ts, src/websimrt.ts) exécute le JavaScript directement, avec la même API. Il tourne dans node, dans la page qu’écritarchec sim --html, dans la page en direct et dans le panneau ▶ de VS Code.archec stubsécritarche.d.tsdans.arche/typings, dans le dossier du fichier principal. Il écrit au même endroit le paquetarchede Python. Le fichier contient :- les signatures de l’API ;
- une interface par message, avec
name; - un type par composant : ses variables, ses ports et ses fonctions, ses états
sous forme d’union de chaînes, et une union
Msgde ce qu’il reçoit ; - les constantes et les énumérations.
Rien n’est écrit à côté du code, et il n’y a pas de
tsconfig.json. Dans VS Code, l’extension écrit le fichier d’elle-même, et son plugin TypeScript fait pointer"arche"et les noms globaux vers lui (voir editor.md). Pourtscen ligne de commande, ajoutez deux lignes à votretsconfig.json;archec stubsles affiche :{ "compilerOptions": { "paths": { "arche": ["./.arche/typings/arche.d.ts"] } }, "include": ["*.ts", ".arche/typings/arche.d.ts"] }Une entrée
pathsassocie"arche", pas"./arche": importez depuis"arche"dans les fichiers quetscvérifie.archec stubs --besideécrit plutôtarche.d.tset untsconfig.jsonà côté des fichiers.ts, comme le faisaient les versions précédentes.
5. Plans de test et gardes#
Arche exécute le code d’un plan de test dans le langage du projet. Ce code, ce
sont le do et le expect d’une étape, un setup ou un stimulus. En
arche-lang, vous l’écrivez en Python, comme avant. Dans un projet TypeScript,
archec l’écrit pour Arche en TypeScript (src/testcode.ts) :
| Écrit | Arche exécute |
|---|---|
abs(c.x) < 0.1 and not c.done |
Math.abs(c.x) < 0.1 && !(c.done) |
send(rx.frames, RC_FRAME(throttle=1200, arm=True)) |
send(rx.frames, RC_FRAME({ throttle: 1200, arm: true })) |
x is None, min, max, round, int, len(xs) |
x === null, Math.min, Math.max, Math.round, Math.trunc, (xs).length |
pass, # note |
rien, // note |
if c: / elif / else: / while c: / for i in range(n): / for x in xs: |
la même chose avec des accolades |
- Le préfixe d’une attente (
within 5ms:,never:,always:) reste tel quel. - Ce qui se lit déjà comme du TypeScript (
a && b,GO({ n: 1 })) reste tel quel. Un bloc```tsest écrit tel quel. - Certaines tournures Python n’ont pas d’équivalent TypeScript simple :
a if c else b,in,//, undef,with,try, une f-string, une lambda. Elles sont signalées (test-typescript). Écrivez-les autrement, ou dans un bloc```ts.
La garde et l’action d’une transition s’écrivent de la même façon dans un projet
TypeScript. [abs(angle) > FALLEN] arrive dans Arche sous la forme
Math.abs(angle) > FALLEN. Les champs du déclencheur sont dans la portée par
leur nom, dans les deux langages.
Dans archec#
| Quoi | Comment |
|---|---|
| Écrire le langage | project { handlers typescript }, component c { handlers python } |
| Déplacer les blocs dans un fichier | archec fmt --extract-code=behaviour.ts --write main.arche (ou --extract-code seul : un fichier par composant, dans son langage) |
| Les types pour l’éditeur | archec stubs main.arche → .arche/typings/arche.d.ts (et le paquet arche s’il y a du Python) |
| L’exécuter | archec sim main.arche (--html, --plant, --batch, --test), archec difftest |
| Le vérifier | archec check : chaque erreur de syntaxe TypeScript sur sa ligne (ts) |
| Changer de langage | archec convert-handlers main.arche --to typescript|python|arche [--component C] [--dry-run] |
Limites#
Ce que archec sim exécute de l’API :
- les attentes
wait,compute,goto, et les fonctions propres à la part ; send,reply(sur le port par lequel le message est arrivé),log,print,warn,fail,now;rand,randint,randn, avec leur graine ;- les durées,
fmt, les fonctions d’aide sur les bits, les conversions d’entiers,message(name).
Ce qu’il n’exécute pas :
recv,select,call,put/get/take,lock, les bits, les flux et les timers,wait_until,clock,pulse,at,component. Chacun arrête le corps avec une erreur qui indique que le simulateur d’Arche l’exécute.Math.randometDate. Ce sont aussi des erreurs, car une exécution doit pouvoir être rejouée.- Le
stated’une poignée de port. Il n’existe pas dansarchec sim.
Le TypeScript qui ne se lit pas :
- un
enumou unnamespace. Ils n’ont pas de JavaScript propre. Utilisez une union de chaînes, ou l’énumération du modèle. - un paramètre
public xde constructeur. - une fonction fléchée
async, dans archec sim. Écrivez plutôt uneasync function.
Un message sans champs, comme message GO: bool, vaut { name, value }.
TypeScript portable#
Les simulateurs exécutent n’importe quel TypeScript. Les générateurs, non.
archec gen --target c|embassy|go et archec difftest ne traduisent que ce que
le langage d’action sait dire, comme pour ```arche. Un corps
TypeScript qui s’en tient à ce sous-ensemble est lu dans l’arbre du langage
d’action. Le C, le Rust ou le Go est ensuite écrit à partir de cet arbre.
Le sous-ensemble :
| TypeScript | Le langage d’action |
|---|---|
let x = e, const x = e (avec une valeur) |
var x = e |
self.x = e, +=, -=, *=, /=, self.n++, --k |
x = e, n += 1, k -= 1 |
if (c) … else if (c) … else …, while (c) { } |
if, while |
for (let i = a; i < b; i++) (ou i <= b, i += 1) |
for i in a..b |
send(self.p, MSG({ k: v })), MSG(), { k } |
send p MSG { k: v } |
await goto("Run"), await wait(ms(2)), wait(ms(self.t)) |
goto Run, wait 2ms, wait t * 1ms |
log(…), print(…) |
log … |
await self.f(a) |
f(a), la fonction de la part |
msg.distance, msg.name |
distance, message (les champs du message reçu) |
self.state === "Idle" |
state == Idle |
=== !== < <= > >= + - * / % && || !, x ** 2 |
== != … and or not, x * x |
Math.abs min max sqrt sin cos atan2, Math.trunc(x), Number(x), Math.PI |
abs …, int(x), float(x), un littéral |
now(), to_s(t), to_ms(t), ns/us/ms/sec(x) |
la même chose |
return, break, continue, nombres, chaînes, true, false, constantes, Color.Red |
la même chose |
Ensuite, la vérification du langage d’action s’exécute. Le corps sort du sous-ensemble s’il contient un nom que la vérification ne connaît pas, un type qui ne convient pas, ou une division de deux entiers. (TypeScript divise les entiers comme des flottants.)
Sont hors du sous-ensemble : un tableau ou un indice (le langage d’action
en a, buf[i] ; ceux de TypeScript n’y sont pas traduits), un ternaire, une chaîne
gabarit, une méthode d’une valeur (list.push), une fonction utilitaire,
reply, recv, un opérateur sur les bits, switch, try. Un tel corps
s’exécute quand même tel quel dans les simulateurs. Les générateurs écrivent à
sa place un TODO contenant le TypeScript, comme ils le font pour le Python
qu’ils ne savent pas traduire. archec check nomme la construction
(ts-portable). C’est une information dans un projet qui ne fait que simuler,
et un avertissement quand un déploiement génère du code pour le composant.
Le on-receive d’un port en TypeScript peut lire son message (msg.distance).
En C, il reçoit le message sous la forme
<part>_on_receive_<port>(self, const void *arche_msg), avec ses champs par
leur nom. Les gardes et les actions d’une transition reçoivent les leurs de la
même façon. Une garde écrite en TypeScript ([msg.force > 0]) est traduite de
la même façon, elle aussi. archec difftest compare donc le TypeScript
qu’exécute le simulateur au C qu’il devient. examples/ts-handlers concorde.
Conversion#
archec convert-handlers main.arche --to typescript|python|arche réécrit sur
place les handlers du modèle dans un autre langage. Il réécrit :
- chaque bloc ```, en gardant sa clôture et son indentation ;
- chaque fichier
code.code "ctrl.py"devient"ctrl.ts". L’ancien fichier est conservé ; supprimez-le quand vous avez terminé. Versarche, chaque fonction devient un bloc```archesur son élément ; - les gardes des transitions ;
handlerssur le projet, ou sur le composant avec--component Ctrl.
Comment chaque langage est lu :
- Depuis
```arche: exactement, par les mêmes traducteurs que ceux qui produisent la copie d’Arche. - Depuis Python : instruction par instruction, à travers ce que dit le langage d’action. C’est la même lecture que celle des générateurs pour Python.
- Depuis TypeScript : instruction par instruction, à travers le sous-ensemble portable ci-dessus.
- Un message reçu : les noms de champs nus de Python (
distance) deviennentmsg.distanceen TypeScript, et lemessagede Python devientmsg.name. Le langage d’action n’a pas de message dans un corps : une instruction qui en lit un reste donc un TODO.
Ce que devient le reste :
- Une instruction qui ne se traduit pas reste en commentaire, avec l’original :
// TODO(convert): <python>, ou# TODO(convert): <ts>en Python. La commande les liste un par un, avec la raison.archec checkle signale (convert-todo) tant que vous ne l’avez pas écrit. - Les commentaires entre les instructions sont conservés. Un commentaire en fin de ligne, ou dans un bloc imbriqué, ne l’est pas.
- Rien n’est écrit quand le résultat contient plus d’erreurs que le modèle.
--dry-runse contente de dire ce qui changerait.
La conversion garde le sens, pas le texte. clamp(x, a, b) revient de
TypeScript sous la forme min(max(x, a), b), et a - b + (c - d) sous la forme
a - b + c - d.
Diagnostics#
| Code | |
|---|---|
handlers |
handlers ne nomme aucun langage de handler |
handlers-language |
du code dans un autre langage que celui dans lequel Arche exécute le projet |
code-language |
un bloc ``` dans un langage qui n’est pas un langage de handler |
ts |
du TypeScript qui ne se lit pas, n’a pas de JavaScript, importe un module ou garde un état en tête de fichier |
ts-portable |
un corps TypeScript hors du sous-ensemble portable : la construction ; les générateurs écrivent un TODO |
convert-todo |
une instruction que archec convert-handlers a laissée en commentaire TODO(convert): |
py-params, py-not-found, py-unused, code-not-found |
comme pour les fichiers .py |
test-typescript |
du code de test, dans un projet TypeScript, qu’archec ne sait pas écrire en TypeScript (§5) |