Importing
archec import turns a model made in another tool into arche-lang. It reads an
Arche project, a SysML v2 model, a CAN DBC file, ASN.1 types, a robot (URDF or
MJCF), a Capella project, Polarion requirements and Python functions. The result is a .arche file
that archec builds at once, so you see its errors straight away.
A first import#
A CAN database (a DBC file) with two nodes and one frame:
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)
In bus.arche, the message and the two nodes are:
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
}
The file also has the can port type, a logical system, a CAN bus with one
processor per node, and a deployment that routes the frame over the bus with id 0x100.
Without -o, the result goes to stdout. What has no place in the language is not
dropped silently: the importers keep it as a comment where it was
(// dbc line N: …), and list it as a note.
An Arche project#
archec import <arche-project> -o <dir> rewrites any Arche project in arche-lang.
archec diff <a> <b> compares two projects as data. Key order, quoting and empty
values do not count; list order does.
How the import works:
- It builds what it wrote and compares the result with the project.
- It fixes each difference on the declaration that made it.
- It repeats until the build gives back exactly the project.
- It then writes the short forms, and copies the files the project refers to
(
assets).
What the language has no word for is written with attr key = value.
A large project was imported this way: antenna control on a Kria KR260, now in its
own private repository. It had seven model files, 211 components, 206 requirements
with their verification blocks, and 54 scenarios with alt and loop fragments.
It also had 1280 traces, and French text with English translations
("Libellé" en "Label"). archec build gives back the very project it came from.
A name in brackets in a text is a checked reference: [REQ-ANT-037],
[kria.ps.app.tracking]. Arche receives it in its own reference form
(KRIA260.yaml#kria.ps.app.tracking), so nothing changes in the project.
A long text puts its translation on the next line, under it. fmt --simplify splits
such lines:
description "Le PS doit faire tourner l'application…"
en "The PS shall run the application…"
In VS Code, a workspace with several projects shows one root per project in the Model and Files views. examples/ has three.
A SysML v2 model#
archec import model.sysml -o model.arche reads a model in SysML v2 textual
notation. The result is built at once, and its errors are listed.
The parser is tolerant. It reads each member of a body: a header up to ;, or a
{ … } body. Only then does it work out what the member is. What it does not know
is not an error.
| SysML v2 | arche-lang |
|---|---|
| the one package around the model | project "Name" (its doc is the description); inner packages are packages |
part def D :> B |
component D extends B; a part def used only by a part at the top (part car : Car) is 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 (~ turns the items around) |
item def M, attribute def S { … }, attribute def T :> Real, enum def E |
message M, struct S, type T = float64, enum E |
an item def also used as data (in cmd : Cmd; in an action, attribute c : Cmd) |
struct CmdData { … } and message Cmd: CmdData. A message is not a type, so the action takes cmd: CmdData |
interface def I { end a : P; end b : ~P; } |
interface I { messages … } (the items of its ends' port defs) |
connect a.p to b.q, connection c connect …, interface i : I connect … |
a.p -> b.q (turned to go from the out end), 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; … }, the initial state first |
transition first A accept e if g then B, accept e then B |
A -> B on e [g]; accept after 10 [s] is a trigger in text, 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 "…" }; a nested requirement derives its parent |
requirement mass : MassReq; (a usage of a requirement def) |
requirement mass { text "…" }. With no text of its own, the text is its definition's doc |
satisfy R by x, verify R |
satisfies R on part x (or on the definition), verifies R |
verification def T { objective { verify R; } } |
test-plan T { verifies R; case T-1 } |
doc /* … */, // and /* … */ comments |
description "…", comments |
Limits of the SysML v2 import#
- Names are global in arche-lang, so
importand qualified names are dropped:A::B::CisC. Two things with the same name in different packages clash. - Types from the standard library (
ScalarValues,ISQ,SI…) map tofloat64,int32,uint32,boolandstring. A quantity takes its unit from its value, not from its type. - Behaviour is Python in Arche. An entry or exit action becomes an empty
on-enteroron-exit. A transition'sdoeffect becomes a comment. An action's steps are left out. Adoaction becomes the state'sdoonly when the part has that action. satisfy R by world.car.enginegoes on the partengineofcar's definition. So it holds for every car.- Expressions are not read. A guard is copied as it is. A default value that is not a literal or a name is left out, with a note.
- Nothing is dropped silently. What has no place becomes a
// sysml line N: …comment where it was (N is its line in the SysML file), and a noteline N: …. This is the case for use cases, calcs, constraints, analysis, allocation, views,subjectandrequirein requirements, connection defs, n-ary connections, and a second state machine in one part. - Metadata (
@X,#X,metadata def) is left out, with a note. - arche-lang has no multiplicity range:
[2..4]becomes[4].[*]on a part is left out.
A CAN DBC#
archec import bus.dbc -o bus.arche reads a CAN database. It writes the same
constructs that archec gen --target dbc reads to write a DBC, so each gives the
other back. For example, take the DBC that gen writes for
examples/autonomous-car, import it, and generate it again: you get the same file,
byte for byte.
| DBC | arche-lang |
|---|---|
BO_ 256 EngineData: 8 ECM |
message EngineData { byte-order …; size 8 }, a wire format; the route's id 0x100 |
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 counts along the frame as the wire format does (a Motorola signal from its most significant bit). Most signals take the message's byte-order; the others say their own |
the sign (-), factor and offset |
signed, scale, offset. A scaled signal is a float32 (float64 past 24 bits). An unscaled one is the smallest uint or int that holds it; a 1-bit one is a bool |
[min|max] |
range min..max, unless it is what the bits carry anyway (or [0|0]) |
SIG_VALTYPE_ … : 1 / 2 |
float32 / float64, sent as its IEEE bits |
VAL_ 512 Gear 0 "Park" 1 "Reverse" … |
enum Gear { Park = 0, Reverse = 1, … }, named after its VAL_TABLE_ when one is the same. A text that is not a name becomes the literal's label |
CM_ BO_, CM_ SG_, CM_ BU_ |
the label of the message, of the field, of the node's component and processor |
BA_ "GenMsgCycleTime" BO_ 256 10; |
period 10ms on the message (gen writes it back as GenMsgCycleTime) |
BU_: ECM TCM |
component ECM, with an out port for each frame it sends and an in port for each frame it receives. The port is can, or can-fd when a frame is longer than 8 bytes or the bus says CAN FD. Each node is also a part of the logical system, a processor of the platform on the bus, and a binary on it in the deployment |
| a frame and its receivers | a link and a route over the bus for each receiver, all at the frame's id (gen writes them as one frame again) |
Limits of the DBC import#
- A multiplexed signal (
m0,m1…) has no place. It becomes a// dbc line N:comment in its message, and the multiplexor (M) is a plain field. - Signal groups, environment variables, value tables that no signal uses, and attributes other than the cycle time and the bus type become comments too, each with a note.
- Each receiver gets the whole frame. When the signals of a frame go to different
nodes,
genlists every receiver on every signal. Vector__XXX(no receiver) is a part of its own.gendoes not list it inBU_.- A frame sent by several nodes (
BO_TX_BU_) is sent by the first one. - A value table stays a comment on its field when the signal is scaled, signed, or longer than 8 bits.
- An IEEE float with a factor or an offset loses them: the language sends a float as its bits.
- Two frames with one name are one message when their signals are the same.
Otherwise the second is renamed (
Name_2). - An extended id is kept as it is, with its bit 31 set, in the route's
id. - The file's own comment (
CM_ "…") becomes a comment at the top.gendoes not write it back.
ASN.1#
archec import types.asn [more.asn…] -o types.arche reads ASN.1 type definitions.
It reads the part of X.680 that describes data.
- Each module becomes a
package. - A module's
IMPORTS … FROM Mis looked up among the modules of the files given. - Names are global in arche-lang. A name that two modules define gets a suffix in
the second one (
Speed_2). - A hyphen becomes an underscore (
Common-Types→Common_Types).
| ASN.1 | arche-lang |
|---|---|
BOOLEAN, REAL |
bool, float64 |
INTEGER (0..30000), INTEGER |
the smallest uint or int that holds it, with range 0..30000; int64 when unbounded |
ENUMERATED { ok, degraded(5), failed } |
enum { ok = 0, degraded = 5, failed = 1 }. Unnumbered items take the smallest free number, as X.680 says |
OCTET STRING (SIZE (4)), OCTET STRING |
byte[4], bytes |
BIT STRING (SIZE (8)) |
bool[8] (bool[] when the size varies) |
IA5String, UTF8String, VisibleString, PrintableString… |
string, with its kind and SIZE in a comment |
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[] (the bounds in a comment) |
| a SEQUENCE that no other type uses | a message (what is sent), its fields inline |
| a CHOICE that no other type uses | its union, and message <Name>_MSG: <Name> |
| an inline SEQUENCE, CHOICE or ENUMERATED in a field | a type of its own, named after its place (Report_mode) |
maxSpeed INTEGER ::= 30000 |
const maxSpeed = 30000 (for INTEGER, BOOLEAN, REAL and string values) |
X ::= Y, X ::= INTEGER (…) |
type X = Y, type X = uint16 range … |
Limits of the ASN.1 import#
Each item below gets a note naming the line. A whole assignment that is not
supported also becomes a // asn1 line N: comment where it was.
- Not supported: information object classes and objects (
CLASS,&field), parameterised types (Pair { T } ::= …), value sets, andCOMPONENTS OF. - Values are read only for INTEGER, BOOLEAN, REAL and string.
- Named numbers on an INTEGER are kept as a comment.
OBJECT IDENTIFIERand the time types are written asstring.- The only constraints read are a value range, a list of single values (read as
their range) and
SIZE.FROM,PATTERN,CONTAININGandWITH COMPONENTSare left out. - Tags (
[3] IMPLICIT) and extension markers (...,[[ … ]]) say how the type is encoded and how it may grow. They are left out. Extension additions are read as ordinary components. - A type named in IMPORTS but found in none of the files becomes
bytes. - The encoding (BER, PER, ACN) is not read. For a bit-exact layout, give the message a wire format.
A robot: URDF and MJCF#
archec import robot.urdf -o robot.arche reads a URDF robot.
archec import scene.xml reads a MuJoCo model (MJCF). A .xml file is recognised
by its root element, <robot> or <mujoco>.
The result has three things:
- a component for the robot. Its bodies are nested inside it, following the
kinematic tree. Each body uses the language's bodies words:
mass,shape,joint. Soarchec gen --target mujocowrites it back. - a part
commandsthat sends to the robot's actuators; - a system with both.
It is written as archec fmt writes, and built at once.
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 |
|---|---|
a URDF <link>, an MJCF <body> |
a component in its parent's, with mass |
| its place in its parent, and its joint (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 comes from URDF's origin rpy, or MJCF's quat, euler, axisangle, xyaxes or zaxis. The joint's damping, and URDF's effort and velocity limits, go in prop <joint> = {…} |
<inertial> |
mass, and prop inertial = {pos, quat, diaginertia | fullinertia}. Without one (MJCF), the mass of the geoms, as MuJoCo computes it |
<collision>, <geom> |
the first one the language can say is the body's shape (box, sphere, capsule, cylinder; with rot when it is turned in its body). The others become prop <name> = {geom: …} with MuJoCo's sizes; a URDF <visual> gets visual: true |
<site> |
prop <name> = {site: sphere, pos, size} |
<transmission>, a <ros2_control> command interface, an MJCF actuator |
a part kind actuator in the body of its joint. Its in command receives a message whose field has the unit (rad for position, rad/s for velocity) and the ctrlrange as range. Also prop kp, prop kv, prop actuator = {type, joint, gear…}. commands sends to it |
a Gazebo or URDF <sensor>, an MJCF sensor or camera |
a part kind sensor in its body, with prop sensor = imu | jointpos | accelerometer…. Its out value sends a message with its units, at its rate (period). width, height, channels and range as the gazebo target reads them |
MJCF <include>, <default> classes, <frame> |
read in, resolved, and folded into what they hold |
MJCF <option timestep gravity>, the first <key> |
solver, prop gravity; each joint's start value (= value) |
Units: lengths are in m, angles in rad, masses in kg. MJCF degrees are turned into radians, and Euler angles and axes into quaternions.
Frames: a body's frame is the source's. Its joint's rot turns it in its parent's
frame. A turn about one axis is written rot z 90deg; any other turn is roll, pitch,
yaw. The body's axis, its shape, its prop records and the bodies in it are in that
frame, as the source says them.
The rest becomes a // urdf: or // mjcf: comment where it was, and a note:
lights, materials, tendons, equalities, contact pairs, Gazebo plugins, mimic
joints, and the keyframes after the first. An attribute archec does not read is a
note.
Limits of the robot import#
- A xacro file must be expanded first:
xacro robot.urdf.xacro > robot.urdf. - A body has one
shapeand onejoint. Its other geoms and joints stay as records, whichgen --target mujocodoes not read. - A mesh is only its file name. Its volume is not computed, so a body with only a
mesh and no
<inertial>has no mass. - Actuator defaults are read from the element's own class entry, then from
general.
Capella#
archec capella exchanges a model with Capella 6.1, in both directions. It runs
the Arche app's own Capella converter (bundled in vendor/arche.js). So archec and
the app's Capella dialog give the same files.
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#
- The model is built.
- Each component goes to the Arcadia level its
layernames: Operational, System, Logical, Physical or EPBS. - Data, messages and interfaces go to the most abstract level that uses them.
- The
.capellafile is checked against the Capella 6.1 metamodel before anything is written. A problem is listed, and the exit code is 1.
What Capella has no place for is listed with the reason. Examples: a derives
between two requirements, or a scenario step on an exchange that is not exported.
To open the result in Capella: File › Import › General › Existing Projects into Workspace.
Import#
The Capella model first becomes the Arche project that the app's import makes:
- one model per Arcadia level;
- laid out as the
.airddraws it (--no-diagramsskips the layout); --prefixsets the file names;--layers oa,sa,la,pa,epbskeeps only some levels.
That project is then rewritten in arche-lang, as archec import does, and built.
Requirements and scenarios become requirement and scenario declarations. The
rest of the model is written too:
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"} }Where the functions and capabilities go:
- When only one level has functions, they go to
functional.yaml, and the capabilities tousecases.yaml. - When several levels have functions, each level keeps its own file. Its
functions, flows and chains say it with
file "dd-la-functions.yaml". - A name that two levels use is written as its address where it would be ambiguous.
- Missions stay as
attrof the capabilities file.
--project dir keeps the intermediate Arche project.
Round trip#
The import records where each element came from, in the <prefix>-capella.yaml
data block. Exporting again gives the elements back their Capella ids. This holds
for components, ports, exchanges, functions and their ports, functional exchanges,
chains, capabilities, missions and property values.
What the app's export makes anew gets new ids: data type literals, state machine regions, chain involvements and scenario lifelines. About 70 to 80% of a model's ids survive.
Python#
archec import x.py translates Python functions into the action language, so
they run in the simulator and on a microcontroller. archec import <dir> -o <out>
does it for every .py of a folder. CPython's own ast reads the file
(python3 on the PATH, or ARCHEC_PYTHON); nothing of the module runs, unless
you ask for the check.
Take 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 holds a component per module, and an interface of the functions
other parts may call through a 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 runs the doctests: archec test numbers.test.arche --sim web.
What is translated#
| Python | arche-lang |
|---|---|
a module prime_check.py |
component PrimeCheck, interface PrimeCheckApi of its public functions that take no list |
def f(n: int) -> float, its docstring |
fn f "first sentence" (n: int64) -> float64, the rest as description, source "file.py:line" |
int, float, bool |
int64, float64 (--option int=int32, --option float=float32), bool |
list[int] as a parameter |
int64[], changed in place as in Python; a function that returns the list it was given returns nothing |
tuple[int, int] as a result, return a, b, q, r = f(x) |
-> (int64, int64), return (a, b), (q, r) = f(x) |
[0] * n, [1, 2, 3] |
a local array: of n items when n is a constant, else of --option max (64) items, with a check that n fits: the function is then embedded-bounded |
a // b, a % b on ints |
floor_div(a, b), floor_mod(a, b) (rounded down, as Python), or / and % where both are known not to be negative |
a / b on ints, x ** y |
a float division; x * x for a small constant power, a loop for an int power, pow for a float one |
for i in range(a, b, s), reversed(range(…)), for x in xs, enumerate(xs) |
for i in a..b step s, a loop down, for x in xs, a counter |
a, b = b, a + b, xs[i], xs[j] = xs[j], xs[i] |
(a, b) = (b, a + b): every value first |
sum(…), any(…), all(…) of a generator or a list |
a loop before the statement |
x if c else y |
a local set by an if |
return f(n - 1), return n * f(n - 1) |
a loop (a tail call), a loop with an accumulator |
math.sqrt, sin, cos, atan2, floor, ceil, gcd, isqrt, pi, e, round, divmod, pow(b, e, m) |
builtins, or a private helper of the component (py_isqrt, py_round…) |
if n < 0: raise ValueError(…) |
log "ValueError: …" and the result's zero; below it, n is known not to be negative |
isinstance(n, int) of a typed n |
what the type says: the check is left out |
A parameter with no type hint takes the type its doctests give it. A generic
list[T] that the doctests sort numbers and strings in becomes a list of numbers.
Embedded, bounded, simulation#
Each function is classified:
- embedded: translated.
- embedded-bounded: translated, with an array of a fixed size (
--option max). - simulation: not translated. Its reason is in a comment, and the function is
simulation-only: it binds by name to the def of the.py(code "x.py"), andarchec simruns it in Python (sim.md); the embedded generators refuse it on a microcontroller. A function that calls one issimulationtoo.
What makes a function simulation: strings, dicts and sets; lists that grow
(append, a new list returned); slices and lists of lists. Classes, try,
with and generators. A recursion that is not a tail call or an accumulation, a
function inside a function, a call of another module. A parameter with no type,
and what a check found. --embedded-only leaves the
simulation functions out. --report report.json writes each function, its
class, its reason, its doctests and its check; a short table goes to stderr.
The differential check#
--check runs each translated function on the same inputs in Python and in the
translation, and compares:
- the inputs: its doctests', then a few drawn from a seed (
--seed) among small values (0, 1, 2, 7, -3, 40, 0.5, lists of 1 to 8 items); - Python: the module, imported and called on each input
(
lib/python/pyimport.py run, 2 s a call); an input Python raises on is not compared; - the simulator: a rig that extends the component calls the function;
- C:
archec gen --target c, a harness that calls it, each call in a process of its own, built withcc; - Rust:
archec gen --target embassy, itsapp.rsbuilt alone withrustc.
An int compares exactly; a float within 1e-9 of its size (1e-5 for float32);
a list item by item, after the call. An int Python gives that int64 does not hold
(factorial(21)) is the function's domain, not a mismatch: the function stays
embedded and the comment above it says from where (// domain: factorial(21) does not fit in int64). Any other difference, a crash or a loop that does not end,
and the function is simulation, the difference as its reason. --checked-only
also keeps out what no input compared.
A module's own import of another package that is not installed is replaced by a
stand-in, so that the functions that do not use it still run.
Limits of the Python import#
- The ints are 64 bits: what grows past them (a factorial,
1 << n) gives other results. The check finds the ones the inputs reach. - The simulator holds an int exactly to 2^53; past it, a value is compared in C and Rust only.
- A negative index (
xs[-1]with a constant isxs[len(xs) - 1]) counts from the end in Python only. - An array is not passed through a port: a function that takes one is not in the interface. A part that needs it extends the component.
- Two modules of one name in two folders: the second gets its folder's name in
front.
--avoid <dir>does the same for the names another package declares. round(x, n)roundsx * 10 ** n: a half may round otherwise than Python, which rounds the exact decimal.
Polarion#
archec polarion writes the work items of a Polarion project as requirements. It
reads them from a JSON export, or straight from the server.
It works for any Polarion project:
- the standard fields are known;
- a custom field is recognised by its name, or named in
polarion.yaml; - what has no place in the language is kept as
attr, so nothing is lost.
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
In VS Code, Arche: Import from Polarion… does the same:
- it asks for the server, the project and the query once, and keeps them in
polarion.yaml; - it asks for the token once, and keeps it in VS Code's secret storage (Arche: Forget the Polarion Token removes it);
- it writes the file, offers to include it, and builds.
The export is what the REST API answers to
GET /rest/v1/projects/{p}/workitems?fields[workitems]=@all. archec reads one page
{data: [...]}, an array of pages, or the file archec polarion pull --save workitems.json writes. archec import workitems.json does the same as
archec polarion workitems.json.
polarion.yaml sits beside main.arche. Every key is optional:
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 (or puid with id: puid) |
the requirement's id |
title |
its name |
description, a …Rationale field (XHTML) |
description, rationale, as plain text (paragraphs, line breaks and list items kept) |
severity (must_have, should_have, nice_to_have, blocker…), else priority (90 … 10) |
priority (critical, high, medium, low) |
status (draft, open, inReview, approved, rejected…) |
status (draft, proposed, approved, implemented, verified, obsolete) |
a …Category… field |
category (the first one; all of them as attr categories) |
a …Method… field (T, A, I, D, test, analysis…) |
method |
an …Owner… field, else the assignee |
owner |
| the document (module) | document: the deliverable documents: names, or one written for it |
id, puid, outline number |
origin "Polarion MYPROJ-123 · REQ-0085 · SRS-4.2" |
a link in a derives: role, to a work item written here or to a requirement of the project |
derives |
| any other link | attr polarion-links = {describes: ["MYPROJ-9"], parent: ["MYPROJ-1"]} |
| any other field, a custom enum or a user relationship | attr <field-name> (costCenter → attr cost-center) |
A value with no meaning in the language (a status weird) is written as a comment
and named in a note. Map it under values:.
With --project (or pull main.arche):
- a requirement the project already declares is left out, and links to it become
derives; - what the output file itself declared is rewritten, so pulling again updates it.