Holarch Language Engine
Référence de l'API du Language Engine
L'interface publique du Holarch Language Engine : une requête JSON en entrée, une réponse JSON en sortie. Cette page liste chaque opération, ses arguments et sa réponse, avec un petit exemple. Elle décrit le Holarch Language Engine 2.0.
Aller à : Exemple · Points d'entrée · Requêtes et réponses · Diagnostics · Erreurs · Enregistrements d'éléments · Opérations · Ensembles de modifications · Limites
Le paquet d'évaluation contient le moteur, la bibliothèque standard, le guide complet du développeur avec une vraie requête et une vraie réponse pour chaque opération, la liste des codes de diagnostic et des exemples exécutables. Le moteur lui-même ne figure pas sur cette page.
Exemple : contrôler un modèle pendant la saisie
L'intégration complète la plus petite : une page avec une zone de texte et un worker qui héberge le moteur. Elle fonctionne telle quelle une fois le paquet d'évaluation décompressé : placez les deux fichiers dans examples/00-quick-start/, servez le dossier du paquet sur l'adresse de bouclage et ouvrez la page.
cd holarch-language-engine-2.0.0
python3 -m http.server 8000 --bind 127.0.0.1
# open http://127.0.0.1:8000/examples/00-quick-start/
La page : index.html
Elle envoie une requête analyze par modification. Chaque requête porte un numéro de révision rev ; le moteur le recopie dans la réponse, si bien que la page ignore les réponses aux requêtes qu'elle a déjà remplacées.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Quick start</title>
</head>
<body>
<textarea id="src" rows="8" cols="60">package Demo {
part def Pump;
part p : Pmp;
}</textarea>
<pre id="out">Starting…</pre>
<script>
const worker = new Worker('worker.js');
const out = document.getElementById('out');
let rev = 0;
worker.onmessage = (ev) => {
const a = ev.data;
if (a.error) { out.textContent = a.message || a.error; return; }
if (a.rev !== rev) return; // an older answer: a newer request is on its way
out.textContent = a.diagnostics.length
? a.diagnostics.map((d) => `${d.range.from}-${d.range.to} ${d.severity} ${d.code} ${JSON.stringify(d.args)}`).join('\n')
: 'No problems.';
};
const check = () => worker.postMessage({ op: 'analyze', doc: 'demo', rev: ++rev, text: document.getElementById('src').value });
document.getElementById('src').addEventListener('input', check);
check();
</script>
</body>
</html>
Le worker : worker.js
Il charge le moteur et répond à chaque message par un seul appel. Les adresses de bouclage n'ont besoin d'aucun jeton de licence.
// Loads the core and answers one JSON request per message. Requests that arrive before the core is ready wait.
importScripts('../../core/holarch_sysml.js'); // defines the global wasm_bindgen
const ready = (async () => {
const bytes = await (await fetch('../../core/holarch_sysml_bg.wasm')).arrayBuffer();
await wasm_bindgen({ module_or_path: bytes });
// Pass your license token here; loopback (127.0.0.1, localhost) needs none.
if (wasm_bindgen.unlock) wasm_bindgen.unlock('');
})();
onmessage = async (ev) => {
await ready;
try {
postMessage(JSON.parse(wasm_bindgen.call(JSON.stringify(ev.data))));
} catch (e) {
postMessage({ error: 'core-fault' }); // a trap: start a new worker to continue
}
};
La requête et la réponse
Pour le texte d'exemple, la page envoie :
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Le moteur répond (jetons et mises à jour des références abrégés) :
{
"rev": 1,
"diagnostics": [
{
"code": "name.unresolved",
"severity": "error",
"range": { "from": 43, "to": 46 },
"args": { "name": "Pmp", "segment": "Pmp" },
"elementId": "…",
"field": "typedBy",
"doc": "demo"
}
],
"tokens": [["keyword", 0, 7], ["ws", 7, 8], ["def", 8, 12], "…"],
"refs": ["…"]
}
rangeest exprimé en unités de code UTF-16, comme les indices de chaînes JavaScript :text.slice(43, 46)vaut"Pmp".codeest stable d'une version à l'autre ; le paquet d'évaluation fournit des messages en anglais pour chaque code (Pmp is not defined here. Check the spelling, or import its package.).tokenssont des triplets[kind, from, to]pour la coloration.
Points d'entrée
Dans le navigateur et dans Node.js, le moteur est un module WebAssembly accompagné d'un petit script de liaison. Ce script définit une seule variable globale, wasm_bindgen : une fonction d'initialisation asynchrone avec ces exports.
| Export | Signature | Remarques |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Instancie le module à partir des octets .wasm, d'un WebAssembly.Module, d'une URL ou d'une Response. À appeler une fois par worker. |
call(request) | string → string | Exécute une requête JSON et renvoie une réponse JSON. Ne lève jamais d'exception, quelle que soit la chaîne d'entrée. Une défaillance interne lève une RuntimeError ; démarrez ensuite un nouveau worker. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Fonctionne avant unlock. |
heap_bytes() | () → number | Octets actuellement occupés par les allocations du moteur. La mémoire WebAssembly ne fait que croître ; comparez les deux valeurs pour savoir combien un nouveau worker économiserait. Fonctionne avant unlock. |
notice() | () → string | L'avis de droit d'auteur. Fonctionne avant unlock. |
unlock(token) | string → string | Applique un jeton de licence pour l'origine du worker et répond {ok, …}, ou {ok: false, reason}. Les origines de bouclage n'ont besoin d'aucun jeton. |
La build serveur pour Python, disponible avec une licence Enterprise, expose call(request: str) -> str et version() -> str avec le même JSON.
Requêtes et réponses
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opsélectionne l'opération. Une opération inconnue répond{"error": "unknown-op"}.revest facultatif : tout nombre que vous envoyez revient inchangé, y compris avec une erreur. Utilisez-le pour associer les réponses à l'état à partir duquel elles ont été calculées.- Les réponses sont des objets JSON. L'ordre des clés n'a aucune signification ; ignorez les clés que vous ne connaissez pas.
- Un JSON mal formé, une requête qui n'est pas un objet ou un argument obligatoire manquant répond
{"error": "bad-request"}. - Le moteur ne lit jamais de fichiers ni le réseau. Tout ce dont il a besoin se trouve dans la requête, dans la bibliothèque chargée avec
library.loadou dans une session de document.
Positions
Chaque position (offset, range.from, range.to, et from/to des modifications et des correspondances de source) est comptée dans les unités de l'appelant : unités de code UTF-16 dans la build WebAssembly, en accord avec les chaînes JavaScript et les positions des éditeurs, et points de code Unicode dans la build Python. Les plages sont semi-ouvertes ; une plage dont from est égal à to marque une position, par exemple l'endroit où manque un ;.
Diagnostics
{
"code": "name.unresolved",
"severity": "error",
"range": { "from": 21, "to": 22 },
"args": { "name": "A", "segment": "A" },
"elementId": "8ff5ac4e-a81a-5828-b557-a0b392e84714",
"field": "typedBy",
"doc": "d1"
}
| Champ | Présent | Signification |
|---|---|---|
code | toujours | Code stable, family.rule. Le paquet d'évaluation liste chaque code avec sa signification et sa correction. |
severity | toujours, sauf dans json_import | "error", "warning" ou "info" (une note sans rien à corriger, comme une représentation textuelle dans un langage que le moteur ne contrôle pas). |
range | opérations sur le texte | L'emplacement dans le texte. Les opérations sur le modèle comme check n'ont ni texte ni plage. |
args | toujours | Valeurs de chaîne pour le message (name, expected, found, …). Peut être vide. |
elementId | diagnostics sémantiques | L'élément dont le contrôle l'a déclenché. |
field | souvent | Le champ d'enregistrement concerné (typedBy, value, body.source, …). |
doc | diagnostics sémantiques de analyze | La valeur doc de la requête, ou null. |
Les listes sont triées par position. Après une erreur de syntaxe, les diagnostics de syntaxe suivants attendent que l'analyseur lise de nouveau un jeton correct, afin qu'une seule erreur ne produise pas une cascade.
Codes d'erreur
| Erreur | Opérations | Signification |
|---|---|---|
bad-request | toutes | JSON mal formé, pas un objet, ou argument obligatoire manquant ou de type incorrect. |
unknown-op | toutes | Aucune opération de ce nom dans cette version. |
limit.input-size | opérations sur le texte et sur les enregistrements | Un texte de plus de 8 Mio (UTF-8), ou des fichiers de bibliothèque de plus de 64 Mio au total. |
limit.nesting | opérations sur les enregistrements, json_import, v1_convert | Une chaîne de propriétaires d'enregistrement (ou d'élément SysML v1) de plus de 512 niveaux. |
limit.elements | v1_convert | Plus de 250 000 éléments et entrées de liste dans le modèle. |
limit.output-size | v1_convert | Le texte converti dépasserait 8 Mio. |
mirror-missing | analyze | mirrorKey désigne des enregistrements que ce worker ne détient pas ; renvoyez records. |
session-missing | check | base n'est pas la session de contrôle conservée ; renvoyez le modèle entier avec une nouvelle clé. |
not-found | shortest_name | target ne figure ni dans les enregistrements ni dans la bibliothèque. |
apply.<reason> | apply | Une modification ne correspond pas aux enregistrements, par exemple apply.id-used ou apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | La position n'est pas sur un nom, le nom appartient à la bibliothèque, ou le nouveau nom n'est pas valide. |
feature-not-licensed | v1_convert | L'opération appartient à un module complémentaire que la licence n'inclut pas. Accompagnée de feature et message. |
not-licensed | toutes | Aucune licence acceptée pour cette origine. Accompagnée de message. |
limit.time, busy | Build Python | Le budget de temps de l'appel est épuisé, ou trop d'appels s'exécutent en même temps. |
Enregistrements d'éléments
Le texte devient des enregistrements d'éléments : un objet JSON qui associe chaque identifiant d'élément à un enregistrement plat. Les opérations sur le modèle prennent et renvoient ce format.
{
"type": "PartUsage",
"owner": "<id of the owning element, or null>",
"order": "a0",
"name": "wheels",
"typedBy": [{ "ref": "<target id or null>", "text": "Wheel" }],
"multiplicity": { "text": "4" },
"fmt": { "…": "printer hints" }
}
| Champ | Forme | Signification |
|---|---|---|
type | chaîne | Métaclasse, comme Package, PartDefinition, PartUsage, ConnectionUsage ou TransitionUsage (les noms de métaclasses SysML v2). Obligatoire. |
owner | identifiant ou null | Élément propriétaire ; null désigne le niveau supérieur. Obligatoire. |
order | chaîne | Position parmi les membres du propriétaire. Comparez comme des chaînes simples, puis par identifiant. Obligatoire. |
role | chaîne | Genre d'appartenance lorsqu'il ne s'agit pas d'un membre ordinaire : subject, actor, require, verify, return, entry, do, exit, then, et d'autres. |
name, shortName | chaîne | Tel que déclaré, sans guillemets. |
visibility | chaîne | public, private ou protected lorsqu'il est écrit. |
flags | objet | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel et d'autres (seul true est stocké) ; direction : in, out ou inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | tableau de références | Relations. |
multiplicity | {text} | Bornes telles qu'écrites ("0..*"). |
value | {text, kind, default?} | kind vaut "=" ou ":=" ; text est l'expression telle qu'écrite. |
body | objet | Selon la métaclasse : extrémités de connecteurs, déclencheurs et effets de transitions, cibles et filtres d'import, texte des commentaires, expressions de contraintes, etc. |
doc | chaîne | Le texte du premier commentaire doc. |
xid, mid, docId | chaîne | Identifiants conservés depuis le JSON importé. |
fmt | objet | Indications pour l'imprimeur de texte. Conservez-les telles quelles, ou supprimez-les lorsque votre modification rend la graphie stockée incorrecte. |
Les références sont de la forme {ref, text, chain?, conj?} : ref est l'identifiant de la cible (null tant qu'elle n'est pas résolue), text le nom tel qu'écrit (un nom qualifié A::B ou une chaîne de caractéristiques a.b.c), chain l'identifiant résolu de chaque segment de la chaîne, et conj: true marque un type conjugué (~P).
Les identifiants sont des UUID en minuscules. lower les dérive de l'argument doc et du chemin de chaque élément, si bien que le même texte et le même doc donnent les mêmes identifiants. sync et diff conservent les identifiants existants et donnent aux nouveaux éléments des identifiants issus de votre seed. Les éléments de la bibliothèque ont les mêmes identifiants dans toutes les versions (lib_id).
Opérations
Les arguments entre crochets sont facultatifs. Chaque requête peut porter rev.
| Opération | Arguments | Réponse |
|---|---|---|
version | — | {core, abi, records, checkParts} : records est la révision du format d'enregistrement ; checkParts indique que check accepte le modèle d'une session en plusieurs parties. |
library.load | files : [{path, text}], les fichiers de bibliothèque .sysml et .kerml dans n'importe quel ordre (64 Mio au plus) | {files, elements, skipped, packages}. Remplace la bibliothèque et efface toutes les sessions de document. |
library.status | — | {files, elements} de la bibliothèque chargée. |
lib_id | qname, par exemple ISQ::MassValue | {id}, l'identifiant de l'élément de bibliothèque correspondant à ce nom. |
lex | text | {tokens, diagnostics} : jetons [kind, from, to] et diagnostics lexicaux. Rapide ; pour un premier affichage. |
roundtrip | text | {text, same, diagnostics} : le texte reconstruit à partir de ses jetons ; un autotest du lexer. |
parse | text | {errors, diagnostics} : syntaxe uniquement, sans résolution des noms. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. L'opération principale de l'éditeur : jetons avec genres sémantiques (def, ref, unresolved), diagnostics syntaxiques et sémantiques, et mises à jour des références. Avec une clé doc, le moteur conserve une session et ne recontrôle que ce qu'une modification peut atteindre ; records résout les noms par rapport au reste du modèle. |
lower | text; [doc] | {records, roots, skipped, diagnostics} : enregistrements d'éléments avec références non résolues, identifiants de niveau supérieur dans l'ordre du texte, et membres ignorés à cause d'erreurs de syntaxe. |
check | records ; [session], ou [session], base, changes ; [load] | {refs, diagnostics} : la cible résolue de chaque référence dont le ref stocké diffère, et des diagnostics avec elementId et field. Avec une clé session, le moteur conserve le modèle ; une requête ultérieure la désigne comme base avec seulement les changes ({id: record or null}), et le moteur ne recontrôle que les packages que les modifications peuvent atteindre, avec la même réponse qu'un contrôle complet. load: "part" envoie un grand modèle en plusieurs requêtes et load: "end" le contrôle, si bien que le modèle entier n'a jamais à être en mémoire sous forme d'une seule requête. {"op": "check.drop"} libère le modèle conservé. |
evaluate | records; [ids] | {values} : pour chaque identifiant d'élément, une valeur {kind, text, …}, où kind vaut number, quantity (avec unit et dimension), boolean, string, unit, sequence, element ou unknown. Affichez text. |
analyze_case | records; [ids] | {cases, requirements} : chaque satisfy avec son statut (satisfied, violated, not-applicable, unknown) et les valeurs de ses contraintes, et chaque cas d'analyse et de vérification avec son résultat. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …}, ou {elementId: null} en dehors d'un nom. |
definition | comme hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | comme hover | {from, to, items} : remplacez from..to par le insert ou le label d'un élément. |
rename | comme hover, plus name | {elementId, changes} : [{from, to, insert}] pour chaque occurrence dans le texte. |
shortest_name | records, target; [context] | {text} : le nom le plus court qui se résout en target depuis context. |
print_records | records; [roots], [dialect] | {text}. Les éléments inchangés s'impriment octet pour octet. |
canon_lines | records ou text ; [roots], [dialect], [per], [ids] | {lines, bytes} : la taille du modèle en lignes canoniques, c'est-à-dire les lignes du texte que le moteur imprime pour lui sans documentation, commentaires ni lignes vides, si bien que le décompte ne dépend pas de la façon dont le texte a été écrit. Avec per, la part de chaque élément ; avec ids, les parts de ces seuls éléments, pour tenir un décompte à jour après une modification. |
print | records; [root], [text] | {text, map, edits?} : le texte, une correspondance de source [{id, from, to}], et les modifications qui transforment le texte fourni en nouveau texte. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics} : l'ensemble de modifications qui fait correspondre les enregistrements au texte, en conservant les identifiants existants. Avec apply: true, les enregistrements avec l'ensemble de modifications appliqué à la place ({count, diagnostics, notApplied, roots, records}), ce qui demande moins de mémoire pour un grand texte. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs} : un brouillon de texte fusionné avec les modifications du modèle faites entre-temps. |
diff | old, new; [base], [seed] | {changes, ids} : l'ensemble de modifications de old vers new, et l'identifiant qu'a chaque élément de new dans le résultat. |
apply | records, changes | {records} avec les modifications appliquées, ou {error: "apply.<reason>"}. |
edits | old, new (chaînes) | {edits} : remplacements minimaux tenant compte des lignes. |
json_export | records; [ext] | {elements} : éléments JSON SysML v2 (@id, @type), y compris les éléments de relation. Avec ext (par défaut), chaque élément porte ce dont json_import a besoin pour restaurer exactement les enregistrements. |
json_import | elements : un tableau, {elements: […]}, ou des versions de données de l'API | {records, diagnostics}. Les identifiants qui ne sont pas des UUID reçoivent des UUID, l'original étant conservé dans xid. Les éléments de genres que le moteur n'interprète pas sont conservés sous forme d'enregistrements opaques que json_export réécrit sans modification, avec une note json.kept-unsupported par genre. |
v1_convert | model : un modèle SysML v1 lu depuis XMI par votre intégration ; [check], [items] | {text, report, diagnostics?, library?} : du texte SysML v2 et un rapport de ce qui a été converti, approché ou écarté. Fait partie du module complémentaire de migration, sous licence séparée. |
Ensembles de modifications
sync et diff renvoient, et apply accepte, un tableau ordonné de modifications. Les créations et déplacements viennent dans l'ordre du document, les propriétaires avant les membres ; les suppressions viennent en dernier.
| Modification | Signification |
|---|---|
{op: "create", id, fields, after?, before?} | Un nouvel élément, placé après ou avant un élément frère, ou en dernier. |
{op: "update", id, patch} | Modifications de champs ; null supprime un champ. Ne modifie jamais owner ni order. |
{op: "move", id, owner, after?, before?} | Un nouveau propriétaire ou une nouvelle position. |
{op: "remove", ids} | Supprime les éléments et tout ce qu'ils possèdent. |
Limites
Au-delà d'une limite, le moteur répond par un diagnostic ou un code d'erreur, jamais par un blocage ou un plantage. Chaque opération prend un temps proportionnel à son entrée.
| Limite | Valeur | Au-delà de la limite |
|---|---|---|
| Taille du texte | 8 Mio (UTF-8) | limit.input-size |
| Longueur de ligne | 64 Kio (UTF-8) | limit.line-length pour chaque ligne trop longue |
| Imbrication des corps | 256 niveaux | limit.nesting ; la partie plus profonde est ignorée |
| Imbrication des expressions | 512 niveaux | limit.expression-depth |
| Chaîne de propriétaires d'enregistrement | 512 niveaux | {error: "limit.nesting"} |
| Fichiers de bibliothèque, au total | 64 Mio | {error: "limit.input-size"} |
| Import JSON | 500 000 éléments | json.too-many-elements ; le reste n'est pas lu |
Modèle SysML v1 (v1_convert) | 250 000 éléments et entrées de liste ; chaînes de propriétaires de 512 niveaux ; texte de 8 Mio | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Nouveau nom dans rename | 1 à 1 000 caractères, sans caractères de contrôle | {error: "rename.invalid-name"} |
La build navigateur n'a pas de limite de temps propre : exécutez-la dans un worker et terminez le worker s'il ne répond pas à temps. Les réponses contiennent du texte issu de l'entrée, comme des noms et de la documentation ; échappez-le comme toute saisie utilisateur avant de l'insérer dans une page.
Versions et stabilité
version() indique la version du moteur et la version de l'interface (abi). Au sein d'une version majeure, les opérations, champs et codes de diagnostic ne sont ni supprimés ni modifiés dans leur signification ; de nouvelles opérations, de nouveaux champs et de nouveaux codes peuvent être ajoutés, ignorez donc ce que vous ne connaissez pas. À partir de la version 2.0, une nouvelle version majeure est annoncée six mois à l'avance.
Essayez le moteur sur vos propres modèles.
L'évaluation est gratuite pendant 60 jours et comprend le guide complet du développeur et les exemples.