Importer
archec import traduit en arche-lang un modèle fait avec un autre outil. Il lit
un projet Arche, un modèle SysML v2, un fichier DBC CAN, des types ASN.1, un
robot (URDF ou MJCF), un projet Capella, des exigences Polarion et des fonctions Python. Le résultat
est un fichier .arche qu’archec compile aussitôt : vous voyez ses erreurs tout
de suite.
Un premier import#
Une base CAN (un fichier DBC) avec deux nœuds et une trame :
VERSION ""
BU_: ECM TCM
BO_ 256 EngineData: 8 ECM
SG_ EngineSpeed : 7|16@0+ (0.25,0) [0|16383.75] "rpm" TCM
BA_ "GenMsgCycleTime" BO_ 256 10;
archec import bus.dbc -o bus.arche
✓ bus.arche — 1 message, 1 field, 2 component, 1 system, 1 route; 0 note(s)
Dans bus.arche, le message et les deux nœuds donnent ceci :
message EngineData {
byte-order big
size 8
period 10ms
EngineSpeed: float32 unit rpm at 0 bits 16 scale 0.25
}
component ECM {
out EngineData: can sends EngineData
}
component TCM {
in EngineData: can receives EngineData
}
Le fichier contient aussi le type de port can, un système logique, un bus CAN
avec un processeur par nœud, et un déploiement qui achemine la trame sur le bus
avec id 0x100.
Sans -o, le résultat part sur la sortie standard. Ce qui n’a pas sa place dans
le langage n’est pas perdu en silence : les importeurs le gardent en commentaire
à l’endroit où il se trouvait (// dbc line N: …) et le signalent dans une
note.
Un projet Arche#
archec import <arche-project> -o <dir> réécrit n’importe quel projet Arche en
arche-lang. archec diff <a> <b> compare deux projets en tant que données.
L’ordre des clés, les guillemets et les valeurs vides ne comptent pas ; l’ordre
des listes, si.
Comment l’import procède :
- Il compile ce qu’il a écrit et compare le résultat au projet.
- Il corrige chaque différence sur la déclaration qui l’a produite.
- Il recommence jusqu’à ce que la compilation redonne exactement le projet.
- Il écrit ensuite les formes courtes et copie les fichiers auxquels le projet
fait référence (
assets).
Ce que le langage ne sait pas dire s’écrit avec attr key = value.
Un gros projet a été importé de cette façon : le contrôle d’une antenne sur une
Kria KR260, aujourd’hui dans son propre dépôt privé. Il comptait sept fichiers
de modèle, 211 composants, 206 exigences avec leurs blocs de vérification, et 54
scénarios avec des fragments alt et loop. Il avait aussi 1280 traces, et des
textes en français avec leur traduction anglaise ("Libellé" en "Label").
archec build redonne exactement le projet d’origine.
Un nom entre crochets dans un texte est une référence vérifiée :
[REQ-ANT-037], [kria.ps.app.tracking]. Arche la reçoit sous sa propre forme
de référence (KRIA260.yaml#kria.ps.app.tracking) : rien ne change donc dans le
projet.
Un texte long place sa traduction sur la ligne suivante, en dessous.
fmt --simplify découpe ces lignes :
description "Le PS doit faire tourner l'application…"
en "The PS shall run the application…"
Dans VS Code, un espace de travail qui contient plusieurs projets montre une racine par projet dans les vues Model et Files. examples/ en contient trois.
Un modèle SysML v2#
archec import model.sysml -o model.arche lit un modèle écrit dans la notation
textuelle de SysML v2. Le résultat est compilé aussitôt, et ses erreurs sont
listées.
L’analyseur est tolérant. Il lit chaque membre d’un corps : un en-tête jusqu’au
;, ou un corps { … }. C’est seulement ensuite qu’il détermine ce qu’est le
membre. Ce qu’il ne connaît pas n’est pas une erreur.
| SysML v2 | arche-lang |
|---|---|
| le package unique qui entoure le modèle | project "Name" (son doc en est la description) ; les packages internes sont des package |
part def D :> B |
component D extends B ; une part def utilisée seulement par une part au premier niveau (part car : Car) devient system Car |
part w : Wheel[4], part x { … } |
part w: Wheel[4], component x { … } |
attribute mass = 1200 [kg], attribute g : Gear = Gear::park |
var mass: float64 = 1200 unit kg, var g: Gear = park |
port def P { out item t : Torque; }, port p : ~P |
port-type P ; in p: P receives Torque (~ inverse le sens des items) |
item def M, attribute def S { … }, attribute def T :> Real, enum def E |
message M, struct S, type T = float64, enum E |
une item def aussi utilisée comme donnée (in cmd : Cmd; dans une action, attribute c : Cmd) |
struct CmdData { … } et message Cmd: CmdData. Un message n’est pas un type : l’action prend donc cmd: CmdData |
interface def I { end a : P; end b : ~P; } |
interface I { messages … } (les items des port defs de ses extrémités) |
connect a.p to b.q, connection c connect …, interface i : I connect … |
a.p -> b.q (orienté pour partir de l’extrémité out), link c a.p -> b.q |
flow of M from a.p to b.q |
a.p -> b.q { carries M } |
exhibit state s : S { entry; then A; state A; … } |
states { state A; … }, l’état initial en premier |
transition first A accept e if g then B, accept e then B |
A -> B on e [g] ; accept after 10 [s] devient un déclencheur en texte, on "after 10 [s]" |
action a : Def { in x : Real; out y : Real; }, perform action |
fn a(x: float64) -> float64 |
requirement <'R1'> massReq /* Mass */ { doc /* … */ } |
requirement R1 "Mass" { text "…" } ; une exigence imbriquée derives de son parent |
requirement mass : MassReq; (un usage d’une requirement def) |
requirement mass { text "…" }. Sans texte propre, son texte est le doc de sa définition |
satisfy R by x, verify R |
satisfies R sur la part x (ou sur la définition), verifies R |
verification def T { objective { verify R; } } |
test-plan T { verifies R; case T-1 } |
doc /* … */, commentaires // et /* … */ |
description "…", commentaires |
Limites de l’import SysML v2#
- Les noms sont globaux en arche-lang : les
importet les noms qualifiés disparaissent.A::B::CdevientC. Deux éléments de même nom dans des packages différents entrent en conflit. - Les types de la bibliothèque standard (
ScalarValues,ISQ,SI…) deviennentfloat64,int32,uint32,booletstring. Une grandeur prend son unité dans sa valeur, pas dans son type. - Dans Arche, le comportement s’écrit en Python. Une action d’entrée ou de
sortie devient un
on-enterou unon-exitvide. L’effetdod’une transition devient un commentaire. Les étapes d’une action sont omises. Une actiondone devient ledode l’état que si la part possède cette action. satisfy R by world.car.enginese place sur la partenginede la définition decar. Elle vaut donc pour toutes les voitures.- Les expressions ne sont pas lues. Une garde est recopiée telle quelle. Une valeur par défaut qui n’est ni un littéral ni un nom est omise, avec une note.
- Rien n’est perdu en silence. Ce qui n’a pas sa place devient un commentaire
// sysml line N: …à l’endroit où il se trouvait (N est sa ligne dans le fichier SysML), et une noteline N: …. C’est le cas des cas d’utilisation, des calcs, des contraintes, des analyses, des allocations, des vues, desubjectetrequiredans les exigences, des connection defs, des connexions n-aires, et d’une seconde machine à états dans une même part. - Les métadonnées (
@X,#X,metadata def) sont omises, avec une note. - arche-lang n’a pas d’intervalle de multiplicité :
[2..4]devient[4].[*]sur une part est omis.
Un DBC CAN#
archec import bus.dbc -o bus.arche lit une base CAN. Il écrit les mêmes
constructions que celles que lit archec gen --target dbc pour écrire un DBC :
chacun redonne donc l’autre. Par exemple, prenez le DBC que gen écrit pour
examples/autonomous-car, importez-le, puis régénérez-le : vous obtenez le même
fichier, octet pour octet.
| DBC | arche-lang |
|---|---|
BO_ 256 EngineData: 8 ECM |
message EngineData { byte-order …; size 8 }, un format de trame ; l’id 0x100 de la route |
SG_ EngineSpeed : 7|16@0+ (0.25,0) [0|16383.75] "rpm" TCM |
EngineSpeed: float32 unit rpm at 0 bits 16 scale 0.25. at compte le long de la trame comme le fait le format de trame (un signal Motorola à partir de son bit de poids fort). La plupart des signaux prennent le byte-order du message ; les autres indiquent le leur |
le signe (-), le facteur et l’offset |
signed, scale, offset. Un signal mis à l’échelle est un float32 (float64 au-delà de 24 bits). Un signal sans échelle est le plus petit uint ou int qui le contient ; un signal d’un bit est un bool |
[min|max] |
range min..max, sauf si c’est de toute façon ce que portent les bits (ou [0|0]) |
SIG_VALTYPE_ … : 1 / 2 |
float32 / float64, envoyé sous forme de ses bits IEEE |
VAL_ 512 Gear 0 "Park" 1 "Reverse" … |
enum Gear { Park = 0, Reverse = 1, … }, nommé d’après sa VAL_TABLE_ quand une table identique existe. Un texte qui n’est pas un nom devient le libellé du littéral |
CM_ BO_, CM_ SG_, CM_ BU_ |
le libellé du message, du champ, du composant et du processeur du nœud |
BA_ "GenMsgCycleTime" BO_ 256 10; |
period 10ms sur le message (gen le réécrit en GenMsgCycleTime) |
BU_: ECM TCM |
component ECM, avec un port out pour chaque trame qu’il envoie et un port in pour chaque trame qu’il reçoit. Le port est can, ou can-fd quand une trame dépasse 8 octets ou que le bus se déclare CAN FD. Chaque nœud est aussi une part du système logique, un processeur de la plateforme sur le bus, et un binaire sur ce processeur dans le déploiement |
| une trame et ses récepteurs | un lien et une route sur le bus pour chaque récepteur, tous à l’id de la trame (gen les réécrit en une seule trame) |
Limites de l’import DBC#
- Un signal multiplexé (
m0,m1…) n’a pas sa place. Il devient un commentaire// dbc line N:dans son message, et le multiplexeur (M) est un champ ordinaire. - Les groupes de signaux, les variables d’environnement, les tables de valeurs qu’aucun signal n’utilise, et les attributs autres que la période et le type de bus deviennent aussi des commentaires, chacun avec une note.
- Chaque récepteur reçoit toute la trame. Quand les signaux d’une trame vont à
des nœuds différents,
genliste tous les récepteurs sur chaque signal. Vector__XXX(aucun récepteur) est une part à part entière.genne la liste pas dansBU_.- Une trame envoyée par plusieurs nœuds (
BO_TX_BU_) est envoyée par le premier. - Une table de valeurs reste un commentaire sur son champ quand le signal est mis à l’échelle, signé, ou plus long que 8 bits.
- Un flottant IEEE avec un facteur ou un offset les perd : le langage envoie un flottant sous forme de ses bits.
- Deux trames de même nom forment un seul message quand leurs signaux sont
identiques. Sinon, la seconde est renommée (
Name_2). - Un id étendu est gardé tel quel, avec son bit 31 à 1, dans l’
idde la route. - Le commentaire propre au fichier (
CM_ "…") devient un commentaire en tête.genne le réécrit pas.
ASN.1#
archec import types.asn [more.asn…] -o types.arche lit des définitions de
types ASN.1. Il lit la partie de X.680 qui décrit les données.
- Chaque module devient un
package. - Le
IMPORTS … FROM Md’un module est cherché parmi les modules des fichiers fournis. - Les noms sont globaux en arche-lang. Un nom que deux modules définissent
reçoit un suffixe dans le second (
Speed_2). - Un tiret devient un tiret bas (
Common-Types→Common_Types).
| ASN.1 | arche-lang |
|---|---|
BOOLEAN, REAL |
bool, float64 |
INTEGER (0..30000), INTEGER |
le plus petit uint ou int qui le contient, avec range 0..30000 ; int64 s’il n’est pas borné |
ENUMERATED { ok, degraded(5), failed } |
enum { ok = 0, degraded = 5, failed = 1 }. Les éléments non numérotés prennent le plus petit numéro libre, comme le dit X.680 |
OCTET STRING (SIZE (4)), OCTET STRING |
byte[4], bytes |
BIT STRING (SIZE (8)) |
bool[8] (bool[] quand la taille varie) |
IA5String, UTF8String, VisibleString, PrintableString… |
string, avec sa sorte et son SIZE en commentaire |
SEQUENCE { a T, b U OPTIONAL, c V DEFAULT x }, SET { … } |
struct { a: T; b: optional U; c: V = x } |
CHOICE { stop NULL, go Speed } |
union { stop; go: Speed } |
SEQUENCE (SIZE (4)) OF T, SEQUENCE SIZE (1..16) OF T |
T[4], T[] (les bornes en commentaire) |
| une SEQUENCE qu’aucun autre type n’utilise | un message (ce qui est envoyé), ses champs en ligne |
| un CHOICE qu’aucun autre type n’utilise | son union, et message <Name>_MSG: <Name> |
| une SEQUENCE, un CHOICE ou un ENUMERATED en ligne dans un champ | un type à part, nommé d’après sa place (Report_mode) |
maxSpeed INTEGER ::= 30000 |
const maxSpeed = 30000 (pour les valeurs INTEGER, BOOLEAN, REAL et chaînes) |
X ::= Y, X ::= INTEGER (…) |
type X = Y, type X = uint16 range … |
Limites de l’import ASN.1#
Chaque point ci-dessous donne lieu à une note qui indique la ligne. Une
affectation entière non prise en charge devient aussi un commentaire
// asn1 line N: à l’endroit où elle se trouvait.
- Non pris en charge : les classes et objets d’information (
CLASS,&field), les types paramétrés (Pair { T } ::= …), les ensembles de valeurs etCOMPONENTS OF. - Les valeurs ne sont lues que pour INTEGER, BOOLEAN, REAL et les chaînes.
- Les nombres nommés d’un INTEGER sont gardés en commentaire.
OBJECT IDENTIFIERet les types temporels s’écriventstring.- Les seules contraintes lues sont un intervalle de valeurs, une liste de
valeurs simples (lue comme leur intervalle) et
SIZE.FROM,PATTERN,CONTAININGetWITH COMPONENTSsont omis. - Les tags (
[3] IMPLICIT) et les marques d’extension (...,[[ … ]]) disent comment le type est encodé et comment il peut évoluer. Ils sont omis. Les ajouts d’extension sont lus comme des composants ordinaires. - Un type nommé dans IMPORTS mais absent de tous les fichiers devient
bytes. - L’encodage (BER, PER, ACN) n’est pas lu. Pour une disposition exacte au bit près, donnez au message un format de trame.
Un robot : URDF et MJCF#
archec import robot.urdf -o robot.arche lit un robot URDF.
archec import scene.xml lit un modèle MuJoCo (MJCF). Un fichier .xml est
reconnu à son élément racine, <robot> ou <mujoco>.
Le résultat comporte trois choses :
- un composant pour le robot. Ses corps y sont imbriqués, en suivant l’arbre
cinématique. Chaque corps utilise les mots du langage pour les
corps :
mass,shape,joint.archec gen --target mujocopeut donc le réécrire. - une part
commandsqui envoie aux actionneurs du robot ; - un système qui réunit les deux.
Il est écrit comme l’écrit archec fmt, et compilé aussitôt.
component Pendulum "pendulum" {
solver 1ms // <option timestep>
component pole {
prop hinge = {damping: 0.05} // what `joint` does not say
physical {
mass 0.3309144262kg // from its geoms, as MuJoCo computes it
shape capsule 0.02m, 0.5m at 0, 0, -0.25m
joint hinge y at 0, 0, 1m range -1.570796327..1.570796327 = 0.5
}
component servo {
kind actuator
prop actuator = {type: position, joint: "hinge"}
prop kp = 10
in command: data receives SERVO_CMD // value: float64 unit rad range -1.5..1.5
}
component angle "angle (jointpos)" {
kind sensor
prop sensor = jointpos
prop joint = "hinge"
out value: data sends ANGLE // value: float64 unit rad
}
}
}| Source | arche-lang |
|---|---|
un <link> URDF, un <body> MJCF |
un composant dans celui de son parent, avec mass |
| sa place dans son parent, et son articulation (URDF revolute, continuous, prismatic, floating, fixed ; MJCF hinge, slide, ball, free) | joint hinge y at x, y, z rot r, p, y range lo..hi = start. rot vient du rpy de l’origine URDF, ou du quat, euler, axisangle, xyaxes ou zaxis MJCF. L’amortissement de l’articulation, et les limites effort et velocity d’URDF, vont dans prop <joint> = {…} |
<inertial> |
mass, et prop inertial = {pos, quat, diaginertia | fullinertia}. Sans lui (MJCF), la masse des geoms, telle que MuJoCo la calcule |
<collision>, <geom> |
la première que le langage sait exprimer devient la shape du corps (box, sphere, capsule, cylinder ; avec rot quand elle est tournée dans son corps). Les autres deviennent prop <name> = {geom: …} avec les dimensions de MuJoCo ; un <visual> URDF reçoit visual: true |
<site> |
prop <name> = {site: sphere, pos, size} |
<transmission>, une interface de commande <ros2_control>, un actionneur MJCF |
une part kind actuator dans le corps de son articulation. Son in command reçoit un message dont le champ porte l’unité (rad en position, rad/s en vitesse) et le ctrlrange en range. Aussi prop kp, prop kv, prop actuator = {type, joint, gear…}. commands lui envoie ses ordres |
un <sensor> Gazebo ou URDF, un capteur ou une caméra MJCF |
une part kind sensor dans son corps, avec prop sensor = imu | jointpos | accelerometer…. Son out value envoie un message avec ses unités, à sa fréquence (period). width, height, channels et range tels que les lit la cible gazebo |
<include> MJCF, classes <default>, <frame> |
lus, résolus et fondus dans ce qu’ils contiennent |
<option timestep gravity> MJCF, la première <key> |
solver, prop gravity ; la valeur de départ de chaque articulation (= value) |
Unités : les longueurs sont en m, les angles en rad, les masses en kg. Les degrés MJCF sont convertis en radians, et les angles d’Euler et les axes en quaternions.
Repères : le repère d’un corps est celui de la source. Le rot de son
articulation le fait tourner dans le repère de son parent. Une rotation autour
d’un seul axe s’écrit rot z 90deg ; toute autre rotation s’écrit en roulis,
tangage, lacet. L’axe du corps, sa forme, ses enregistrements prop et les
corps qu’il contient sont dans ce repère, tels que la source les donne.
Le reste devient un commentaire // urdf: ou // mjcf: à l’endroit où il se
trouvait, avec une note : lumières, matériaux, tendons, égalités, paires de
contact, plugins Gazebo, articulations mimic, et les keyframes après la
première. Un attribut qu’archec ne lit pas donne lieu à une note.
Limites de l’import de robots#
- Un fichier xacro doit d’abord être développé :
xacro robot.urdf.xacro > robot.urdf. - Un corps a une seule
shapeet une seulejoint. Ses autres geoms et articulations restent des enregistrements, quegen --target mujocone lit pas. - Un maillage se réduit à son nom de fichier. Son volume n’est pas calculé : un
corps qui n’a qu’un maillage et pas d’
<inertial>n’a donc pas de masse. - Les valeurs par défaut des actionneurs sont lues d’abord dans l’entrée de
classe propre à l’élément, puis dans
general.
Capella#
archec capella échange un modèle avec Capella 6.1, dans les deux sens. Il
utilise le convertisseur Capella de l’application Arche elle-même (embarqué
dans vendor/arche.js). archec et la boîte de dialogue Capella de
l’application produisent donc les mêmes fichiers.
archec capella main.arche -o project.zip # → a Capella project, as the archive Capella imports
archec capella main.arche -o project/ # → the same project as a folder
archec capella model.capella -o model/ # → arche-lang (the .capella's fragments and .aird beside it are read)
archec capella project.zip -o model/ # → arche-lang, from a Capella project exported as an archive
Export#
- Le modèle est compilé.
- Chaque composant va au niveau Arcadia que nomme son
layer: Operational, System, Logical, Physical ou EPBS. - Les données, messages et interfaces vont au niveau le plus abstrait qui les utilise.
- Le fichier
.capellaest vérifié par rapport au métamodèle de Capella 6.1 avant toute écriture. Chaque problème est listé, et le code de sortie vaut 1.
Ce pour quoi Capella n’a pas de place est listé avec la raison. Par exemple :
un derives entre deux exigences, ou une étape de scénario sur un échange qui
n’est pas exporté.
Pour ouvrir le résultat dans Capella : File › Import › General › Existing Projects into Workspace.
Import#
Le modèle Capella devient d’abord le projet Arche que produit l’import de l’application :
- un modèle par niveau Arcadia ;
- disposé comme le dessine le
.aird(--no-diagramssaute la mise en page) ; --prefixfixe les noms de fichiers ;--layers oa,sa,la,pa,epbsne garde que certains niveaux.
Ce projet est ensuite réécrit en arche-lang, comme le fait archec import, puis
compilé. Les exigences et les scénarios deviennent des déclarations
requirement et scenario. Le reste du modèle est écrit lui aussi :
system-function fly "Fly" { // a function, its parts inside it
system-function steer "Steer" {
kind route
allocated dd-sa.drone // allocated to a component, by path
in order "Order" receives command // its ports and what they carry
}
}
function-flow read-stick.stick -> steer.order as orders { name "Orders"; carries command }
function-chain branching "Branching" { step or { kind or }; edge or -> steer { when "armed" } }
use-case fly-a-mission "Fly a mission" { // a capability
involves dd-sa.pilot, dd-sa.drone, steer, pilot-chain, command
}
property colour { type string; kinds system; group physical } // a property value's definition
component drone "Drone" { mass 1.5; prop certified = true; prop physical = {colour: "red"} }Où vont les fonctions et les capabilities :
- Quand un seul niveau a des fonctions, elles vont dans
functional.yaml, et les capabilities dansusecases.yaml. - Quand plusieurs niveaux ont des fonctions, chaque niveau garde son propre
fichier. Ses fonctions, flux et chaînes l’indiquent avec
file "dd-la-functions.yaml". - Un nom utilisé par deux niveaux est écrit sous forme d’adresse là où il serait ambigu.
- Les missions restent des
attrdu fichier des capabilities.
--project dir conserve le projet Arche intermédiaire.
Aller-retour#
L’import enregistre l’origine de chaque élément dans le bloc de données
<prefix>-capella.yaml. Un nouvel export redonne aux éléments leurs ids
Capella. Cela vaut pour les composants, ports, échanges, fonctions et leurs
ports, échanges fonctionnels, chaînes, capabilities, missions et valeurs de
propriétés.
Ce que l’export de l’application recrée de zéro reçoit de nouveaux ids : les littéraux des types de données, les régions des machines à états, les participations aux chaînes et les lignes de vie des scénarios. Environ 70 à 80 % des ids d’un modèle survivent.
Python#
archec import x.py traduit des fonctions Python dans le langage d’action, pour
qu’elles tournent dans le simulateur et sur un microcontrôleur. archec import <dir> -o <out>
le fait pour chaque .py d’un dossier. C’est l’ast de CPython lui-même qui lit le fichier
(python3 dans le PATH, ou ARCHEC_PYTHON) ; rien du module ne s’exécute, sauf
si vous demandez la vérification.
Prenons numbers.py :
def gcd(a: int, b: int) -> int:
"""
The greatest common divisor of a and b.
>>> gcd(48, 18)
6
"""
a, b = abs(a), abs(b)
while b:
a, b = b, a % b
return a
def insertion_sort(xs: list[int]) -> list[int]:
"""
Sorts xs in place.
>>> insertion_sort([3, 1, 2])
[1, 2, 3]
"""
for i in range(1, len(xs)):
key = xs[i]
j = i - 1
while j >= 0 and xs[j] > key:
xs[j + 1] = xs[j]
j -= 1
xs[j + 1] = key
return xs
def word_count(text: str) -> dict[str, int]:
"""Counts each word."""
counts: dict[str, int] = {}
for w in text.split():
counts[w] = counts.get(w, 0) + 1
return counts
archec import numbers.py -o numbers.arche --check
embedded numbers.py:4 gcd ✓ 8 compared
embedded numbers.py:35 insertion_sort ✓ 7 compared
simulation numbers.py:52 word_count — the parameter text is a str: strings are not translated
1 module(s), 3 function(s): 2 embedded, 0 embedded-bounded, 1 simulation; checked against Python in simulator, C, Rust: 2 agree, 0 downgraded
✓ 2 file(s) in . — 1 component(s)
numbers.arche contient un composant par module, et une interface des fonctions
que d’autres parts peuvent appeler à travers un port :
interface NumbersApi "numbers.py" {
fn gcd(a: int64, b: int64) -> int64
}
component Numbers "Small number helpers" {
source "numbers.py"
code "numbers.py"
in api: provides NumbersApi
fn gcd "The greatest common divisor of a and b" (a: int64, b: int64) -> int64 {
source "numbers.py:4"
```arche
var a_: int64 = a
var b_: int64 = b
(a_, b_) = (abs(a_), abs(b_))
while b_ != 0 {
(a_, b_) = (b_, floor_mod(a_, b_))
}
return a_
```
}
// it changes xs in place and returns it: here it returns nothing, xs is sorted where it is
fn insertion_sort "Sorts xs in place" (xs: int64[]) {
source "numbers.py:35"
```arche
…
```
}
// simulation only: the parameter text is a str: strings are not translated
fn word_count "Counts each word" (text: string) {
simulation-only
source "numbers.py:52"
}
}
numbers.test.arche lance les doctests : archec test numbers.test.arche --sim web.
Ce qui est traduit#
| Python | arche-lang |
|---|---|
un module prime_check.py |
component PrimeCheck, interface PrimeCheckApi de ses fonctions publiques qui ne prennent pas de liste |
def f(n: int) -> float, sa docstring |
fn f "first sentence" (n: int64) -> float64, le reste en description, source "file.py:line" |
int, float, bool |
int64, float64 (--option int=int32, --option float=float32), bool |
list[int] comme paramètre |
int64[], modifié sur place comme en Python ; une fonction qui renvoie la liste qu’on lui a donnée ne renvoie rien |
tuple[int, int] comme résultat, return a, b, q, r = f(x) |
-> (int64, int64), return (a, b), (q, r) = f(x) |
[0] * n, [1, 2, 3] |
un tableau local : de n éléments quand n est une constante, sinon de --option max (64) éléments, avec une vérification que n y tient : la fonction est alors embedded-bounded |
a // b, a % b sur des entiers |
floor_div(a, b), floor_mod(a, b) (arrondi vers le bas, comme Python), ou / et % là où les deux sont connus pour ne pas être négatifs |
a / b sur des entiers, x ** y |
une division flottante ; x * x pour une petite puissance constante, une boucle pour une puissance entière, pow pour une puissance flottante |
for i in range(a, b, s), reversed(range(…)), for x in xs, enumerate(xs) |
for i in a..b step s, une boucle descendante, for x in xs, un compteur |
a, b = b, a + b, xs[i], xs[j] = xs[j], xs[i] |
(a, b) = (b, a + b) : chaque valeur d’abord |
sum(…), any(…), all(…) d’un générateur ou d’une liste |
une boucle avant l’instruction |
x if c else y |
une variable locale fixée par un if |
return f(n - 1), return n * f(n - 1) |
une boucle (un appel terminal), une boucle avec un accumulateur |
math.sqrt, sin, cos, atan2, floor, ceil, gcd, isqrt, pi, e, round, divmod, pow(b, e, m) |
des fonctions intégrées, ou une fonction utilitaire privée du composant (py_isqrt, py_round…) |
if n < 0: raise ValueError(…) |
log "ValueError: …" et le zéro du résultat ; en dessous, n est connu pour ne pas être négatif |
isinstance(n, int) d’un n typé |
ce que dit le type : la vérification est omise |
Un paramètre sans annotation de type prend le type que lui donnent ses doctests. Une
list[T] générique dans laquelle les doctests trient des nombres et des chaînes devient une liste de nombres.
Embarqué, borné, simulation#
Chaque fonction est classée :
- embedded : traduite.
- embedded-bounded : traduite, avec un tableau de taille fixe (
--option max). - simulation : non traduite. Sa raison est dans un commentaire, et la fonction est
simulation-only: elle se lie par son nom au def du.py(code "x.py"), etarchec siml’exécute en Python (sim.md) ; les générateurs embarqués la refusent sur un microcontrôleur. Une fonction qui en appelle une est aussisimulation.
Ce qui rend une fonction simulation : les chaînes, les dicts et les sets ; les listes qui grandissent
(append, une nouvelle liste renvoyée) ; les tranches et les listes de listes. Les classes, try,
with et les générateurs. Une récursion qui n’est ni un appel terminal ni une accumulation, une
fonction dans une fonction, un appel à un autre module. Un paramètre sans type,
et ce qu’une vérification a trouvé. --embedded-only laisse de côté les
fonctions simulation. --report report.json écrit chaque fonction, sa
classe, sa raison, ses doctests et sa vérification ; un petit tableau va sur stderr.
La vérification différentielle#
--check exécute chaque fonction traduite sur les mêmes entrées en Python et dans la
traduction, et compare :
- les entrées : celles de ses doctests, puis quelques-unes tirées d’une graine (
--seed) parmi de petites valeurs (0, 1, 2, 7, -3, 40, 0.5, des listes de 1 à 8 éléments) ; - Python : le module, importé et appelé sur chaque entrée
(
lib/python/pyimport.py run, 2 s par appel) ; une entrée sur laquelle Python lève une exception n’est pas comparée ; - le simulateur : un banc qui étend le composant appelle la fonction ;
- C :
archec gen --target c, un harnais qui l’appelle, chaque appel dans un processus à part, compilé aveccc; - Rust :
archec gen --target embassy, sonapp.rscompilé seul avecrustc.
Un entier se compare exactement ; un flottant à 1e-9 près de sa taille (1e-5 pour float32) ;
une liste élément par élément, après l’appel. Un entier que donne Python et que int64 ne contient pas
(factorial(21)) relève du domaine de la fonction, ce n’est pas un écart : la fonction reste
embedded et le commentaire au-dessus dit à partir d’où (// domain: factorial(21) does not fit in int64).
Toute autre différence, un plantage ou une boucle qui ne finit pas,
et la fonction est simulation, avec la différence comme raison. --checked-only
écarte aussi ce qu’aucune entrée n’a comparé.
Un import d’un autre paquet non installé, fait par le module lui-même, est remplacé par un
substitut, pour que les fonctions qui ne l’utilisent pas tournent quand même.
Limites de l’import Python#
- Les entiers font 64 bits : ce qui les dépasse (une factorielle,
1 << n) donne d’autres résultats. La vérification trouve ceux que les entrées atteignent. - Le simulateur représente un entier exactement jusqu’à 2^53 ; au-delà, une valeur n’est comparée qu’en C et en Rust.
- Un indice négatif (
xs[-1]avec une constante devientxs[len(xs) - 1]) ne compte depuis la fin qu’en Python. - Un tableau ne passe pas par un port : une fonction qui en prend un n’est pas dans l’interface. Une part qui en a besoin étend le composant.
- Deux modules du même nom dans deux dossiers : le second reçoit le nom de son dossier
devant.
--avoid <dir>fait de même pour les noms qu’un autre paquet déclare. round(x, n)arronditx * 10 ** n: une moitié peut s’arrondir autrement qu’en Python, qui arrondit le décimal exact.
Polarion#
archec polarion écrit les work items d’un projet Polarion sous forme
d’exigences. Il les lit depuis un export JSON, ou directement sur le serveur.
Il fonctionne pour n’importe quel projet Polarion :
- les champs standard sont connus ;
- un champ personnalisé est reconnu à son nom, ou nommé dans
polarion.yaml; - ce qui n’a pas sa place dans le langage est gardé en
attr: rien n’est perdu.
archec polarion workitems.json --project main.arche -o spec/polarion.arche # an export
POLARION_TOKEN=… archec polarion pull main.arche # the server
archec polarion pull main.arche --dry-run # the request, not sent
Dans VS Code, Arche: Import from Polarion… fait la même chose :
- il demande une seule fois le serveur, le projet et la requête, et les garde
dans
polarion.yaml; - il demande une seule fois le jeton, et le garde dans le stockage secret de VS Code (Arche: Forget the Polarion Token le supprime) ;
- il écrit le fichier, propose de l’inclure, puis compile.
L’export est ce que l’API REST répond à
GET /rest/v1/projects/{p}/workitems?fields[workitems]=@all. archec lit une
page {data: [...]}, un tableau de pages, ou le fichier qu’écrit
archec polarion pull --save workitems.json. archec import workitems.json
fait la même chose que archec polarion workitems.json.
polarion.yaml se trouve à côté de main.arche. Toutes les clés sont
facultatives :
url: https://polarion.example.com/polarion # pull: the server
project: MYPROJ # pull: the project id
query: "type:requirement AND NOT status:rejected"
out: spec/polarion.arche # where the requirements go (else -o, else stdout)
id: id # id (MYPROJ-123) | puid
documents: # a Polarion document → the project's deliverable
System Requirements: SRS
modules: [System] # only the documents whose id contains one of these
fields: # a field → what it is in the language
verifMethod: method # description text rationale priority status
testLevel: attr test-level # category method owner origin, attr <name>, skip
legacyType: skip
values: # a property's Polarion values → the language's
status: { inReview: proposed }
method: { R: inspection }
derives: [parent, satisfies, refines] # the link roles that are `derives`
| Polarion | arche-lang |
|---|---|
id (ou puid avec id: puid) |
l’id de l’exigence |
title |
son nom |
description, un champ …Rationale (XHTML) |
description, rationale, en texte brut (paragraphes, retours à la ligne et éléments de liste conservés) |
severity (must_have, should_have, nice_to_have, blocker…), sinon priority (90 … 10) |
priority (critical, high, medium, low) |
status (draft, open, inReview, approved, rejected…) |
status (draft, proposed, approved, implemented, verified, obsolete) |
un champ …Category… |
category (le premier ; tous en attr categories) |
un champ …Method… (T, A, I, D, test, analysis…) |
method |
un champ …Owner…, sinon la personne assignée |
owner |
| le document (module) | document : le livrable que nomme documents:, ou un livrable créé pour lui |
id, puid, numéro de plan |
origin "Polarion MYPROJ-123 · REQ-0085 · SRS-4.2" |
un lien dans un rôle de derives:, vers un work item écrit ici ou vers une exigence du projet |
derives |
| tout autre lien | attr polarion-links = {describes: ["MYPROJ-9"], parent: ["MYPROJ-1"]} |
| tout autre champ, une énumération personnalisée ou une relation vers un utilisateur | attr <field-name> (costCenter → attr cost-center) |
Une valeur qui n’a pas de sens dans le langage (un statut weird) est écrite en
commentaire et signalée dans une note. Associez-la à une valeur sous values:.
Avec --project (ou pull main.arche) :
- une exigence que le projet déclare déjà est omise, et les liens vers elle
deviennent des
derives; - ce que le fichier de sortie déclarait lui-même est réécrit : un nouveau pull le met donc à jour.