How-to guides › Import models

How-to guides

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:

  1. It builds what it wrote and compares the result with the project.
  2. It fixes each difference on the declaration that made it.
  3. It repeats until the build gives back exactly the project.
  4. 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 import and qualified names are dropped: A::B::C is C. Two things with the same name in different packages clash.
  • Types from the standard library (ScalarValues, ISQ, SI…) map to float64, int32, uint32, bool and string. 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-enter or on-exit. A transition's do effect becomes a comment. An action's steps are left out. A do action becomes the state's do only when the part has that action.
  • satisfy R by world.car.engine goes on the part engine of car'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 note line N: …. This is the case for use cases, calcs, constraints, analysis, allocation, views, subject and require in 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, gen lists every receiver on every signal.
  • Vector__XXX (no receiver) is a part of its own. gen does not list it in BU_.
  • 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. gen does 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 M is 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, and COMPONENTS OF.
  • Values are read only for INTEGER, BOOLEAN, REAL and string.
  • Named numbers on an INTEGER are kept as a comment.
  • OBJECT IDENTIFIER and the time types are written as string.
  • The only constraints read are a value range, a list of single values (read as their range) and SIZE. FROM, PATTERN, CONTAINING and WITH COMPONENTS are 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. So archec gen --target mujoco writes it back.
  • a part commands that 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
    }
  }
}
Diagram: pendulum
What archec draws from this code: pendulum
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 shape and one joint. Its other geoms and joints stay as records, which gen --target mujoco does 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#

  1. The model is built.
  2. Each component goes to the Arcadia level its layer names: Operational, System, Logical, Physical or EPBS.
  3. Data, messages and interfaces go to the most abstract level that uses them.
  4. The .capella file 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 .aird draws it (--no-diagrams skips the layout);
  • --prefix sets the file names;
  • --layers oa,sa,la,pa,epbs keeps 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"} }
Diagram: Drone
What archec draws from this code: Drone

Where the functions and capabilities go:

  • When only one level has functions, they go to functional.yaml, and the capabilities to usecases.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 attr of 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"), and archec sim runs it in Python (sim.md); the embedded generators refuse it on a microcontroller. A function that calls one is simulation too.

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:

  1. 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);
  2. 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;
  3. the simulator: a rig that extends the component calls the function;
  4. C: archec gen --target c, a harness that calls it, each call in a process of its own, built with cc;
  5. Rust: archec gen --target embassy, its app.rs built alone with rustc.

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 is xs[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) rounds x * 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.