Holarch Language Engine
API-Referenz der Language Engine
Die öffentliche Schnittstelle der Holarch Language Engine: eine JSON-Anfrage hinein, eine JSON-Antwort heraus. Diese Seite listet jede Operation, ihre Argumente und ihre Antwort auf, mit einem kleinen Beispiel. Sie beschreibt Holarch Language Engine 2.0.
Springen zu: Beispiel · Einstiegspunkte · Anfragen und Antworten · Diagnosen · Fehler · Elementdatensätze · Operationen · Änderungssätze · Grenzen
Das Evaluierungspaket enthält die Engine, die Standardbibliothek, das vollständige Entwicklerhandbuch mit einer echten Anfrage und Antwort für jede Operation, die Liste der Diagnosecodes und lauffähige Beispiele. Die Engine selbst ist nicht auf dieser Seite.
Beispiel: ein Modell beim Tippen prüfen
Die kleinste vollständige Integration: eine Seite mit einem Textfeld und ein Worker, der die Engine beherbergt. Sie läuft unverändert, sobald das Evaluierungspaket entpackt ist: Legen Sie beide Dateien in examples/00-quick-start/ ab, stellen Sie den Paketordner unter der Loopback-Adresse bereit und öffnen Sie die Seite.
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/
Die Seite: index.html
Sie sendet pro Änderung eine analyze-Anfrage. Jede Anfrage trägt eine Revisionsnummer rev; die Engine kopiert sie in die Antwort, sodass die Seite Antworten auf bereits ersetzte Anfragen verwirft.
<!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>
Der Worker: worker.js
Er lädt die Engine und beantwortet jede Nachricht mit einem Aufruf. Loopback-Adressen benötigen kein Lizenz-Token.
// 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
}
};
Anfrage und Antwort
Für den Beispieltext sendet die Seite:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Die Engine antwortet (Token und Referenzaktualisierungen gekürzt):
{
"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": ["…"]
}
rangewird in UTF-16-Codeeinheiten angegeben, wie JavaScript-String-Indizes:text.slice(43, 46)ist"Pmp".codeist über Versionen hinweg stabil; das Evaluierungspaket enthält englische Meldungen für jeden Code (Pmp is not defined here. Check the spelling, or import its package.).tokenssind Tripel[kind, from, to]für die Hervorhebung.
Einstiegspunkte
Im Browser und in Node.js ist die Engine ein WebAssembly-Modul mit einem kleinen Glue-Skript. Das Glue-Skript definiert ein globales Objekt, wasm_bindgen: eine asynchrone Init-Funktion mit diesen Exporten.
| Export | Signatur | Hinweise |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Instanziiert das Modul aus den .wasm-Bytes, einem WebAssembly.Module, einer URL oder einer Response. Einmal pro Worker aufrufen. |
call(request) | string → string | Führt eine JSON-Anfrage aus und gibt eine JSON-Antwort zurück. Wirft bei keiner Eingabezeichenkette eine Ausnahme. Ein interner Fehler wirft einen RuntimeError; starten Sie danach einen neuen Worker. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Funktioniert vor unlock. |
heap_bytes() | () → number | Bytes, die die Allokationen der Engine aktuell belegen. WebAssembly-Speicher wächst nur; vergleichen Sie beide Werte, um zu sehen, wie viel ein neuer Worker einsparen würde. Funktioniert vor unlock. |
notice() | () → string | Der Urheberrechtshinweis. Funktioniert vor unlock. |
unlock(token) | string → string | Wendet ein Lizenz-Token für den Origin des Workers an und antwortet mit {ok, …} oder {ok: false, reason}. Loopback-Origins benötigen kein Token. |
Der Server-Build für Python, verfügbar mit einer Enterprise-Lizenz, stellt call(request: str) -> str und version() -> str mit demselben JSON bereit.
Anfragen und Antworten
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opwählt die Operation. Eine unbekannte Operation antwortet mit{"error": "unknown-op"}.revist optional: Jede Zahl, die Sie senden, kommt unverändert zurück, auch bei einem Fehler. Verwenden Sie sie, um Antworten dem Zustand zuzuordnen, aus dem sie berechnet wurden.- Antworten sind JSON-Objekte. Die Reihenfolge der Schlüssel hat keine Bedeutung; ignorieren Sie Schlüssel, die Sie nicht kennen.
- Fehlerhaftes JSON, eine Anfrage, die kein Objekt ist, oder ein fehlendes Pflichtargument antwortet mit
{"error": "bad-request"}. - Die Engine liest nie Dateien oder das Netzwerk. Alles, was sie braucht, steht in der Anfrage, in der mit
library.loadgeladenen Bibliothek oder in einer Dokumentsitzung.
Offsets
Jede Position (offset, range.from, range.to sowie from/to von Bearbeitungen und Source Maps) zählt in den Einheiten des Aufrufers: UTF-16-Codeeinheiten im WebAssembly-Build, passend zu JavaScript-Strings und Editor-Offsets, und Unicode-Codepoints im Python-Build. Bereiche sind halboffen; ein Bereich mit from gleich to markiert eine Position, etwa dort, wo ein ; fehlt.
Diagnosen
{
"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"
}
| Feld | Vorhanden | Bedeutung |
|---|---|---|
code | immer | Stabiler Code, family.rule. Das Evaluierungspaket listet jeden Code mit Bedeutung und Behebung auf. |
severity | immer, außer in json_import | "error", "warning" oder "info" (ein Hinweis ohne zu behebenden Fehler, etwa eine textuelle Repräsentation in einer Sprache, die die Engine nicht prüft). |
range | Textoperationen | Wo im Text. Modelloperationen wie check haben keinen Text und keinen Bereich. |
args | immer | Zeichenkettenwerte für die Meldung (name, expected, found, …). Kann leer sein. |
elementId | semantische Diagnosen | Das Element, dessen Prüfung sie ausgelöst hat. |
field | häufig | Das betroffene Datensatzfeld (typedBy, value, body.source, …). |
doc | Semantische Diagnosen von analyze | Der doc-Wert der Anfrage oder null. |
Listen sind nach Position sortiert. Nach einem Syntaxfehler warten weitere Syntaxdiagnosen, bis der Parser wieder ein gültiges Token liest, sodass ein Fehler keine Kaskade erzeugt.
Fehlercodes
| Fehler | Operationen | Bedeutung |
|---|---|---|
bad-request | alle | Fehlerhaftes JSON, kein Objekt oder ein Pflichtargument, das fehlt oder den falschen Typ hat. |
unknown-op | alle | Keine solche Operation in dieser Version. |
limit.input-size | Text- und Datensatzoperationen | Ein Text über 8 MiB (UTF-8) oder Bibliotheksdateien über insgesamt 64 MiB. |
limit.nesting | Datensatzoperationen, json_import, v1_convert | Eine Besitzerkette von Datensätzen (oder SysML-v1-Elementen), die tiefer als 512 ist. |
limit.elements | v1_convert | Mehr als 250.000 Elemente und Listeneinträge im Modell. |
limit.output-size | v1_convert | Der konvertierte Text würde 8 MiB überschreiten. |
mirror-missing | analyze | mirrorKey benennt Datensätze, die dieser Worker nicht hält; senden Sie records erneut. |
session-missing | check | base ist nicht die gehaltene Prüfsitzung; senden Sie das ganze Modell mit einem neuen Schlüssel erneut. |
not-found | shortest_name | target ist weder in den Datensätzen noch in der Bibliothek. |
apply.<reason> | apply | Eine Änderung passt nicht zu den Datensätzen, etwa apply.id-used oder apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | Der Offset liegt nicht auf einem Namen, der Name gehört zur Bibliothek, oder der neue Name ist ungültig. |
feature-not-licensed | v1_convert | Die Operation gehört zu einem Add-on, das die Lizenz nicht enthält. Kommt mit feature und message. |
not-licensed | alle | Keine akzeptierte Lizenz für diesen Origin. Kommt mit message. |
limit.time, busy | Python-Build | Das Zeitbudget des Aufrufs ist abgelaufen, oder zu viele Aufrufe laufen gleichzeitig. |
Elementdatensätze
Text wird zu Elementdatensätzen: einem JSON-Objekt, das jede Element-ID einem flachen Datensatz zuordnet. Die Modelloperationen nehmen und liefern dieses 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" }
}
| Feld | Form | Bedeutung |
|---|---|---|
type | String | Metaklasse, etwa Package, PartDefinition, PartUsage, ConnectionUsage oder TransitionUsage (die Metaklassennamen von SysML v2). Pflichtfeld. |
owner | ID oder null | Besitzendes Element; null ist die oberste Ebene. Pflichtfeld. |
order | String | Position unter den Mitgliedern des Besitzers. Als einfache Zeichenketten vergleichen, dann nach ID. Pflichtfeld. |
role | String | Art der Mitgliedschaft, wenn es kein gewöhnliches Mitglied ist: subject, actor, require, verify, return, entry, do, exit, then und andere. |
name, shortName | String | Wie deklariert, ohne Anführungszeichen. |
visibility | String | public, private oder protected, wenn geschrieben. |
flags | Objekt | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel und andere (nur true wird gespeichert); direction: in, out oder inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | Array von Referenzen | Beziehungen. |
multiplicity | {text} | Grenzen wie geschrieben ("0..*"). |
value | {text, kind, default?} | kind ist "=" oder ":="; text ist der Ausdruck wie geschrieben. |
body | Objekt | Je Metaklasse: Konnektorenden, Auslöser und Effekte von Transitionen, Importziele und Filter, Kommentartext, Ausdrücke von Randbedingungen und so weiter. |
doc | String | Der Text des ersten doc-Kommentars. |
xid, mid, docId | String | Aus importiertem JSON übernommene IDs. |
fmt | Objekt | Hinweise für den Printer. Lassen Sie sie unverändert oder löschen Sie sie, wenn Ihre Änderung die gespeicherte Schreibweise falsch macht. |
Referenzen sind {ref, text, chain?, conj?}: ref ist die Ziel-ID (null, solange nicht aufgelöst), text der Name wie geschrieben (ein qualifizierter Name A::B oder eine Feature-Kette a.b.c), chain die aufgelöste ID jedes Kettensegments, und conj: true kennzeichnet einen konjugierten Typ (~P).
IDs sind UUIDs in Kleinbuchstaben. lower leitet sie aus dem Argument doc und dem Pfad jedes Elements ab, sodass derselbe Text und dasselbe doc dieselben IDs ergeben. sync und diff behalten bestehende IDs und geben neuen Elementen IDs aus Ihrem seed. Bibliothekselemente haben in jeder Version dieselben IDs (lib_id).
Operationen
Argumente in Klammern sind optional. Jede Anfrage kann rev tragen.
| Operation | Argumente | Antwort |
|---|---|---|
version | — | {core, abi, records, checkParts}: records ist die Revision des Datensatzformats; checkParts gibt an, dass check das Modell einer Sitzung in Teilen annimmt. |
library.load | files: [{path, text}], die .sysml- und .kerml-Bibliotheksdateien in beliebiger Reihenfolge (höchstens 64 MiB) | {files, elements, skipped, packages}. Ersetzt die Bibliothek und löscht jede Dokumentsitzung. |
library.status | — | {files, elements} der geladenen Bibliothek. |
lib_id | qname, etwa ISQ::MassValue | {id}, die ID des Bibliothekselements für diesen Namen. |
lex | text | {tokens, diagnostics}: Token [kind, from, to] und lexikalische Diagnosen. Schnell; für eine erste Darstellung. |
roundtrip | text | {text, same, diagnostics}: der aus seinen Token neu aufgebaute Text; ein Selbsttest des Lexers. |
parse | text | {errors, diagnostics}: nur Syntax, keine Namensauflösung. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. Die Hauptoperation des Editors: Token mit semantischen Arten (def, ref, unresolved), Syntax- und semantische Diagnosen sowie Referenzaktualisierungen. Mit einem doc-Schlüssel hält die Engine eine Sitzung und prüft nur erneut, was eine Bearbeitung erreichen kann; records lösen Namen gegen den Rest des Modells auf. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: Elementdatensätze mit nicht aufgelösten Referenzen, die IDs der obersten Ebene in Textreihenfolge und Mitglieder, die wegen Syntaxfehlern übersprungen wurden. |
check | records; [session], oder [session], base, changes; [load] | {refs, diagnostics}: das aufgelöste Ziel jeder Referenz, deren gespeichertes ref abweicht, und Diagnosen mit elementId und field. Mit einem session-Schlüssel hält die Engine das Modell; eine spätere Anfrage benennt es als base mit nur den changes ({id: record or null}), und die Engine prüft nur die Pakete erneut, die die Änderungen erreichen können, mit derselben Antwort wie eine vollständige Prüfung. load: "part" sendet ein großes Modell in mehreren Anfragen, und load: "end" prüft es, sodass das ganze Modell nie als eine Anfrage im Speicher liegen muss. {"op": "check.drop"} gibt das gehaltene Modell frei. |
evaluate | records; [ids] | {values}: pro Element-ID ein Wert {kind, text, …}, wobei kind number, quantity (mit unit und dimension), boolean, string, unit, sequence, element oder unknown ist. Zeigen Sie text an. |
analyze_case | records; [ids] | {cases, requirements}: jedes satisfy mit seinem Status (satisfied, violated, not-applicable, unknown) und den Werten der Randbedingungen sowie jeder Analyse- und Verifikationsfall mit seinem Ergebnis. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …} oder {elementId: null} abseits eines Namens. |
definition | wie hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | wie hover | {from, to, items}: Ersetzen Sie from..to durch insert oder label eines Eintrags. |
rename | wie hover, plus name | {elementId, changes}: [{from, to, insert}] für jedes Vorkommen im Text. |
shortest_name | records, target; [context] | {text}: der kürzeste Name, der von context aus zu target auflöst. |
print_records | records; [roots], [dialect] | {text}. Unveränderte Elemente werden Byte für Byte ausgegeben. |
canon_lines | records oder text; [roots], [dialect], [per], [ids] | {lines, bytes}: die Größe des Modells in kanonischen Zeilen, also den Zeilen des Textes, den die Engine dafür ohne Dokumentation, Kommentare oder Leerzeilen ausgibt, sodass die Zahl nicht davon abhängt, wie der Text geschrieben wurde. Mit per der Anteil jedes Elements; mit ids nur die Anteile dieser Elemente, um eine Zählung nach einer Änderung aktuell zu halten. |
print | records; [root], [text] | {text, map, edits?}: der Text, eine Source Map [{id, from, to}] und die Bearbeitungen, die den gegebenen Text in den neuen überführen. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: der Änderungssatz, der die Datensätze an den Text angleicht, unter Beibehaltung bestehender IDs. Mit apply: true stattdessen die Datensätze mit angewendetem Änderungssatz ({count, diagnostics, notApplied, roots, records}), was bei einem großen Text weniger Speicher braucht. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: ein Textentwurf, zusammengeführt mit zwischenzeitlich vorgenommenen Modelländerungen. |
diff | old, new; [base], [seed] | {changes, ids}: der Änderungssatz von old nach new und die ID, die jedes Element von new im Ergebnis hat. |
apply | records, changes | {records} mit angewendeten Änderungen oder {error: "apply.<reason>"}. |
edits | old, new (Strings) | {edits}: minimale, zeilenbewusste Ersetzungen. |
json_export | records; [ext] | {elements}: SysML-v2-JSON-Elemente (@id, @type), einschließlich Beziehungselementen. Mit ext (Standard) trägt jedes Element, was json_import braucht, um die Datensätze exakt wiederherzustellen. |
json_import | elements: ein Array, {elements: […]} oder API-Datenversionen | {records, diagnostics}. IDs, die keine UUIDs sind, erhalten UUIDs, wobei das Original in xid erhalten bleibt. Elemente von Arten, die die Engine nicht interpretiert, bleiben als opake Datensätze erhalten, die json_export unverändert zurückschreibt, mit einem Hinweis json.kept-unsupported pro Art. |
v1_convert | model: ein SysML-v1-Modell, das Ihre Integration aus XMI gelesen hat; [check], [items] | {text, report, diagnostics?, library?}: SysML-v2-Text und ein Bericht darüber, was konvertiert, angenähert oder verworfen wurde. Teil des Migrations-Add-ons, separat lizenziert. |
Änderungssätze
sync und diff liefern, und apply nimmt, ein geordnetes Array von Änderungen. Erstellungen und Verschiebungen kommen in Dokumentreihenfolge, Besitzer vor Mitgliedern; Entfernungen kommen zuletzt.
| Änderung | Bedeutung |
|---|---|
{op: "create", id, fields, after?, before?} | Ein neues Element, nach oder vor einem Geschwisterelement oder als letztes platziert. |
{op: "update", id, patch} | Feldänderungen; null löscht ein Feld. Ändert nie owner oder order. |
{op: "move", id, owner, after?, before?} | Ein neuer Besitzer oder eine neue Position. |
{op: "remove", ids} | Entfernt die Elemente und alles, was sie besitzen. |
Grenzen
Über einer Grenze antwortet die Engine mit einer Diagnose oder einem Fehlercode, nie mit einem Hängen oder Absturz. Jede Operation braucht Zeit im Verhältnis zu ihrer Eingabe.
| Grenze | Wert | Über der Grenze |
|---|---|---|
| Textgröße | 8 MiB (UTF-8) | limit.input-size |
| Zeilenlänge | 64 KiB (UTF-8) | limit.line-length für jede lange Zeile |
| Verschachtelung von Rümpfen | 256 Ebenen | limit.nesting; der tiefere Teil wird übersprungen |
| Verschachtelung von Ausdrücken | 512 Ebenen | limit.expression-depth |
| Besitzerkette von Datensätzen | 512 Ebenen | {error: "limit.nesting"} |
| Bibliotheksdateien, insgesamt | 64 MiB | {error: "limit.input-size"} |
| JSON-Import | 500.000 Elemente | json.too-many-elements; der Rest wird nicht gelesen |
SysML-v1-Modell (v1_convert) | 250.000 Elemente und Listeneinträge; Besitzerketten 512 Ebenen; Text 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Neuer Name in rename | 1 bis 1.000 Zeichen, keine Steuerzeichen | {error: "rename.invalid-name"} |
Der Browser-Build hat keine eigene Zeitgrenze: Führen Sie ihn in einem Worker aus und beenden Sie den Worker, wenn er nicht rechtzeitig antwortet. Antworten enthalten Text aus der Eingabe, etwa Namen und Dokumentation; maskieren Sie ihn wie jede Nutzereingabe, bevor Sie ihn in eine Seite einfügen.
Versionen und Stabilität
version() meldet die Engine-Version und die Schnittstellenversion (abi). Innerhalb einer Hauptversion werden Operationen, Felder und Diagnosecodes weder entfernt noch in ihrer Bedeutung geändert; neue Operationen, Felder und Codes können hinzukommen, ignorieren Sie also, was Sie nicht kennen. Ab Version 2.0 wird eine neue Hauptversion sechs Monate im Voraus angekündigt.
Testen Sie die Engine an Ihren eigenen Modellen.
Die Evaluierung ist 60 Tage kostenlos und enthält das vollständige Entwicklerhandbuch und Beispiele.