Holarch Language Engine
Dokumentacja API Language Engine
Publiczny interfejs Holarch Language Engine: jedno żądanie JSON na wejściu, jedna odpowiedź JSON na wyjściu. Ta strona wymienia każdą operację, jej argumenty i odpowiedź, z jednym małym przykładem. Opisuje Holarch Language Engine 2.0.
Przejdź do: Przykład · Punkty wejścia · Żądania i odpowiedzi · Komunikaty diagnostyczne · Błędy · Rekordy elementów · Operacje · Zestawy zmian · Limity
Pakiet ewaluacyjny zawiera silnik, bibliotekę standardową, pełny przewodnik programisty z prawdziwym żądaniem i odpowiedzią dla każdej operacji, listę kodów diagnostycznych i działające przykłady. Samego silnika nie ma na tej stronie.
Przykład: sprawdzanie modelu podczas pisania
Najmniejsza kompletna integracja: strona z polem tekstowym i worker, w którym działa silnik. Działa bez zmian po rozpakowaniu pakietu ewaluacyjnego: umieść oba pliki w examples/00-quick-start/, udostępnij folder pakietu pod adresem pętli zwrotnej i otwórz stronę.
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/
Strona: index.html
Wysyła jedno żądanie analyze na każdą zmianę. Każde żądanie niesie numer rewizji rev; silnik kopiuje go do odpowiedzi, dzięki czemu strona odrzuca odpowiedzi na żądania, które już zastąpiła.
<!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>
Worker: worker.js
Ładuje silnik i odpowiada na każdą wiadomość jednym wywołaniem. Adresy pętli zwrotnej nie wymagają tokenu licencji.
// 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
}
};
Żądanie i odpowiedź
Dla przykładowego tekstu strona wysyła:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Silnik odpowiada (tokeny i aktualizacje odwołań skrócone):
{
"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": ["…"]
}
rangejest wyrażony w jednostkach kodu UTF-16, tak samo jak indeksy ciągów w JavaScript:text.slice(43, 46)to"Pmp".codejest stały między wydaniami; pakiet ewaluacyjny zawiera angielskie komunikaty dla każdego kodu (Pmp is not defined here. Check the spelling, or import its package.).tokensto trójki[kind, from, to]do podświetlania.
Punkty wejścia
W przeglądarce i w Node.js silnik jest modułem WebAssembly z małym skryptem łączącym. Skrypt ten definiuje jedną zmienną globalną, wasm_bindgen: asynchroniczną funkcję inicjującą z tymi eksportami.
| Eksport | Sygnatura | Uwagi |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Tworzy instancję modułu z bajtów .wasm, obiektu WebAssembly.Module, adresu URL lub obiektu Response. Wywołaj raz na workera. |
call(request) | string → string | Wykonuje jedno żądanie JSON i zwraca jedną odpowiedź JSON. Nie zgłasza wyjątku dla żadnego ciągu wejściowego. Wewnętrzny błąd zgłasza RuntimeError; potem uruchom nowego workera. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Działa przed unlock. |
heap_bytes() | () → number | Bajty zajmowane obecnie przez alokacje silnika. Pamięć WebAssembly tylko rośnie; porównaj obie wartości, aby zobaczyć, ile zaoszczędziłby nowy worker. Działa przed unlock. |
notice() | () → string | Informacja o prawach autorskich. Działa przed unlock. |
unlock(token) | string → string | Stosuje token licencji dla źródła (origin) workera i odpowiada {ok, …} lub {ok: false, reason}. Źródła pętli zwrotnej nie wymagają tokenu. |
Kompilacja serwerowa dla Pythona, dostępna z licencją Enterprise, udostępnia call(request: str) -> str i version() -> str z tym samym JSON.
Żądania i odpowiedzi
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opwybiera operację. Nieznana operacja daje odpowiedź{"error": "unknown-op"}.revjest opcjonalny: każda wysłana liczba wraca bez zmian, również z błędem. Służy do dopasowania odpowiedzi do stanu, z którego zostały obliczone.- Odpowiedzi są obiektami JSON. Kolejność kluczy nie ma znaczenia; ignoruj klucze, których nie znasz.
- Niepoprawny JSON, żądanie, które nie jest obiektem, lub brak wymaganego argumentu daje odpowiedź
{"error": "bad-request"}. - Silnik nigdy nie czyta plików ani sieci. Wszystko, czego potrzebuje, jest w żądaniu, w bibliotece załadowanej przez
library.loadlub w sesji dokumentu.
Przesunięcia
Każda pozycja (offset, range.from, range.to oraz from/to edycji i map źródłowych) jest liczona w jednostkach wywołującego: w jednostkach kodu UTF-16 w kompilacji WebAssembly, zgodnie z ciągami JavaScript i przesunięciami edytora, oraz w punktach kodowych Unicode w kompilacji dla Pythona. Zakresy są półotwarte; zakres, w którym from równa się to, oznacza pozycję, na przykład miejsce, gdzie brakuje ;.
Komunikaty diagnostyczne
{
"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"
}
| Pole | Obecne | Znaczenie |
|---|---|---|
code | zawsze | Stały kod, family.rule. Pakiet ewaluacyjny wymienia każdy kod z jego znaczeniem i poprawką. |
severity | zawsze, z wyjątkiem json_import | "error", "warning" lub "info" (uwaga, która nie wymaga poprawki, na przykład reprezentacja tekstowa w języku, którego silnik nie sprawdza). |
range | operacje tekstowe | Miejsce w tekście. Operacje na modelu, takie jak check, nie mają tekstu ani zakresu. |
args | zawsze | Wartości tekstowe do komunikatu (name, expected, found, …). Może być puste. |
elementId | semantyczne komunikaty diagnostyczne | Element, którego kontrola go zgłosiła. |
field | często | Pole rekordu, którego dotyczy (typedBy, value, body.source, …). |
doc | semantyczne komunikaty diagnostyczne analyze | Wartość doc z żądania lub null. |
Listy są posortowane według pozycji. Po błędzie składni kolejne komunikaty składniowe czekają, aż parser znów odczyta poprawny token, więc jeden błąd nie wywołuje kaskady.
Kody błędów
| Błąd | Operacje | Znaczenie |
|---|---|---|
bad-request | wszystkie | Niepoprawny JSON, nie obiekt albo brak wymaganego argumentu lub argument niewłaściwego typu. |
unknown-op | wszystkie | Brak takiej operacji w tej wersji. |
limit.input-size | operacje tekstowe i na rekordach | Tekst większy niż 8 MiB (UTF-8) lub pliki biblioteki łącznie większe niż 64 MiB. |
limit.nesting | operacje na rekordach, json_import, v1_convert | Łańcuch właścicieli rekordu (lub elementu SysML v1) głębszy niż 512. |
limit.elements | v1_convert | Ponad 250 000 elementów i pozycji list w modelu. |
limit.output-size | v1_convert | Przekonwertowany tekst przekroczyłby 8 MiB. |
mirror-missing | analyze | mirrorKey wskazuje rekordy, których ten worker nie przechowuje; wyślij records ponownie. |
session-missing | check | base nie jest zachowaną sesją kontroli; wyślij cały model ponownie z nowym kluczem. |
not-found | shortest_name | target nie występuje w rekordach ani w bibliotece. |
apply.<reason> | apply | Zmiana nie pasuje do rekordów, na przykład apply.id-used lub apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | Przesunięcie nie wskazuje nazwy, nazwa należy do biblioteki albo nowa nazwa jest nieprawidłowa. |
feature-not-licensed | v1_convert | Operacja należy do dodatku, którego licencja nie obejmuje. Zwracana z feature i message. |
not-licensed | wszystkie | Brak zaakceptowanej licencji dla tego źródła. Zwracana z message. |
limit.time, busy | Kompilacja dla Pythona | Wyczerpał się budżet czasu wywołania lub jednocześnie trwa zbyt wiele wywołań. |
Rekordy elementów
Tekst staje się rekordami elementów: obiektem JSON, który przypisuje każdemu identyfikatorowi elementu płaski rekord. Operacje na modelu przyjmują i zwracają ten 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" }
}
| Pole | Postać | Znaczenie |
|---|---|---|
type | ciąg | Metaklasa, na przykład Package, PartDefinition, PartUsage, ConnectionUsage lub TransitionUsage (nazwy metaklas SysML v2). Wymagane. |
owner | identyfikator lub null | Element będący właścicielem; null oznacza najwyższy poziom. Wymagane. |
order | ciąg | Pozycja wśród członków właściciela. Porównuj jako zwykłe ciągi, a potem według identyfikatora. Wymagane. |
role | ciąg | Rodzaj członkostwa, gdy nie jest to zwykły członek: subject, actor, require, verify, return, entry, do, exit, then i inne. |
name, shortName | ciąg | Tak, jak zadeklarowano, bez cudzysłowów. |
visibility | ciąg | public, private lub protected, jeśli zapisano. |
flags | obiekt | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel i inne (zapisywane jest tylko true); direction: in, out lub inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | tablica odwołań | Relacje. |
multiplicity | {text} | Granice tak, jak zapisano ("0..*"). |
value | {text, kind, default?} | kind to "=" lub ":="; text to wyrażenie tak, jak zapisano. |
body | obiekt | Zależnie od metaklasy: końce konektorów, wyzwalacze i efekty przejść, cele i filtry importu, tekst komentarzy, wyrażenia ograniczeń i tak dalej. |
doc | ciąg | Tekst pierwszego komentarza doc. |
xid, mid, docId | ciąg | Identyfikatory zachowane z zaimportowanego JSON. |
fmt | obiekt | Wskazówki dla drukarki tekstu. Zachowaj bez zmian lub usuń, gdy twoja zmiana sprawia, że zapisana pisownia jest błędna. |
Odwołania mają postać {ref, text, chain?, conj?}: ref to identyfikator celu (null, dopóki nierozwiązane), text to nazwa tak, jak zapisano (nazwa kwalifikowana A::B lub łańcuch cech a.b.c), chain to rozwiązany identyfikator każdego segmentu łańcucha, a conj: true oznacza typ sprzężony (~P).
Identyfikatory to UUID zapisane małymi literami. lower wyprowadza je z argumentu doc i ścieżki każdego elementu, więc ten sam tekst i ten sam doc dają te same identyfikatory. sync i diff zachowują istniejące identyfikatory i nadają nowym elementom identyfikatory z twojego seed. Elementy biblioteki mają te same identyfikatory w każdej wersji (lib_id).
Operacje
Argumenty w nawiasach kwadratowych są opcjonalne. Każde żądanie może zawierać rev.
| Operacja | Argumenty | Odpowiedź |
|---|---|---|
version | — | {core, abi, records, checkParts}: records to rewizja formatu rekordów; checkParts informuje, że check przyjmuje model sesji w częściach. |
library.load | files: [{path, text}], pliki biblioteki .sysml i .kerml w dowolnej kolejności (najwyżej 64 MiB) | {files, elements, skipped, packages}. Zastępuje bibliotekę i czyści każdą sesję dokumentu. |
library.status | — | {files, elements} załadowanej biblioteki. |
lib_id | qname, na przykład ISQ::MassValue | {id}, identyfikator elementu biblioteki dla tej nazwy. |
lex | text | {tokens, diagnostics}: tokeny [kind, from, to] i leksykalne komunikaty diagnostyczne. Szybkie; do pierwszego wyświetlenia. |
roundtrip | text | {text, same, diagnostics}: tekst odtworzony z tokenów; autotest leksera. |
parse | text | {errors, diagnostics}: tylko składnia, bez rozwiązywania nazw. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. Główna operacja edytora: tokeny z rodzajami semantycznymi (def, ref, unresolved), składniowe i semantyczne komunikaty diagnostyczne oraz aktualizacje odwołań. Z kluczem doc silnik utrzymuje sesję i ponownie sprawdza tylko to, czego może dotyczyć edycja; records rozwiązują nazwy względem reszty modelu. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: rekordy elementów z nierozwiązanymi odwołaniami, identyfikatory najwyższego poziomu w kolejności tekstu oraz członkowie pominięci z powodu błędów składni. |
check | records; [session] albo [session], base, changes; [load] | {refs, diagnostics}: rozwiązany cel każdego odwołania, którego zapisany ref się różni, oraz komunikaty diagnostyczne z elementId i field. Z kluczem session silnik zachowuje model; późniejsze żądanie wskazuje go jako base tylko ze zmianami changes ({id: record or null}), a silnik ponownie sprawdza tylko pakiety, których mogą dotyczyć zmiany, z taką samą odpowiedzią jak przy pełnej kontroli. load: "part" wysyła duży model w kilku żądaniach, a load: "end" go sprawdza, więc cały model nigdy nie musi być w pamięci jako jedno żądanie. {"op": "check.drop"} zwalnia zachowany model. |
evaluate | records; [ids] | {values}: dla każdego identyfikatora elementu wartość {kind, text, …}, gdzie kind to number, quantity (z unit i dimension), boolean, string, unit, sequence, element lub unknown. Wyświetlaj text. |
analyze_case | records; [ids] | {cases, requirements}: każde satisfy ze statusem (satisfied, violated, not-applicable, unknown) i wartościami ograniczeń oraz każdy przypadek analizy i weryfikacji z wynikiem. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …} lub {elementId: null} poza nazwą. |
definition | jak hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | jak hover | {from, to, items}: zastąp from..to wartością insert lub label pozycji. |
rename | jak hover, plus name | {elementId, changes}: [{from, to, insert}] dla każdego wystąpienia w tekście. |
shortest_name | records, target; [context] | {text}: najkrótsza nazwa, która z context rozwiązuje się do target. |
print_records | records; [roots], [dialect] | {text}. Niezmienione elementy są drukowane bajt w bajt. |
canon_lines | records lub text; [roots], [dialect], [per], [ids] | {lines, bytes}: rozmiar modelu w wierszach kanonicznych, czyli wierszach tekstu, który silnik drukuje dla modelu bez dokumentacji, komentarzy i pustych wierszy, więc liczba nie zależy od sposobu zapisania tekstu. Z per udział każdego elementu; z ids tylko udziały tych elementów, aby utrzymać aktualną liczbę po zmianie. |
print | records; [root], [text] | {text, map, edits?}: tekst, mapa źródłowa [{id, from, to}] oraz edycje, które zamieniają podany tekst w nowy. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: zestaw zmian, który dopasowuje rekordy do tekstu, zachowując istniejące identyfikatory. Z apply: true zamiast tego rekordy z zastosowanym zestawem zmian ({count, diagnostics, notApplied, roots, records}), co przy dużym tekście wymaga mniej pamięci. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: szkic tekstu scalony ze zmianami modelu wprowadzonymi w międzyczasie. |
diff | old, new; [base], [seed] | {changes, ids}: zestaw zmian od old do new oraz identyfikator, jaki każdy element new ma w wyniku. |
apply | records, changes | {records} z zastosowanymi zmianami lub {error: "apply.<reason>"}. |
edits | old, new (ciągi) | {edits}: minimalne zamiany uwzględniające wiersze. |
json_export | records; [ext] | {elements}: elementy SysML v2 JSON (@id, @type), łącznie z elementami relacji. Z ext (domyślnie) każdy element zawiera to, czego json_import potrzebuje do dokładnego odtworzenia rekordów. |
json_import | elements: tablica, {elements: […]} lub wersje danych API | {records, diagnostics}. Identyfikatory, które nie są UUID, otrzymują UUID, a oryginał jest zachowywany w xid. Elementy rodzajów, których silnik nie interpretuje, są zachowywane jako nieprzezroczyste rekordy, które json_export zapisuje z powrotem bez zmian, z jedną uwagą json.kept-unsupported na rodzaj. |
v1_convert | model: model SysML v1 odczytany z XMI przez twoją integrację; [check], [items] | {text, report, diagnostics?, library?}: tekst SysML v2 i raport z tego, co zostało przekonwertowane, przybliżone lub pominięte. Część dodatku do migracji, licencjonowanego osobno. |
Zestawy zmian
sync i diff zwracają, a apply przyjmuje uporządkowaną tablicę zmian. Utworzenia i przeniesienia występują w kolejności dokumentu, właściciele przed członkami; usunięcia są na końcu.
| Zmiana | Znaczenie |
|---|---|
{op: "create", id, fields, after?, before?} | Nowy element, umieszczony po rodzeństwie, przed nim lub na końcu. |
{op: "update", id, patch} | Zmiany pól; null usuwa pole. Nigdy nie zmienia owner ani order. |
{op: "move", id, owner, after?, before?} | Nowy właściciel lub nowa pozycja. |
{op: "remove", ids} | Usuwa elementy i wszystko, czego są właścicielami. |
Limity
Po przekroczeniu limitu silnik odpowiada komunikatem diagnostycznym lub kodem błędu, nigdy zawieszeniem ani awarią. Czas każdej operacji jest proporcjonalny do jej danych wejściowych.
| Limit | Wartość | Po przekroczeniu limitu |
|---|---|---|
| Rozmiar tekstu | 8 MiB (UTF-8) | limit.input-size |
| Długość wiersza | 64 KiB (UTF-8) | limit.line-length dla każdego długiego wiersza |
| Zagnieżdżenie treści | 256 poziomów | limit.nesting; głębsza część jest pomijana |
| Zagnieżdżenie wyrażeń | 512 poziomów | limit.expression-depth |
| Łańcuch właścicieli rekordu | 512 poziomów | {error: "limit.nesting"} |
| Pliki biblioteki, łącznie | 64 MiB | {error: "limit.input-size"} |
| Import JSON | 500 000 elementów | json.too-many-elements; reszta nie jest odczytywana |
Model SysML v1 (v1_convert) | 250 000 elementów i pozycji list; łańcuchy właścicieli do 512 poziomów; tekst do 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Nowa nazwa w rename | Od 1 do 1000 znaków, bez znaków sterujących | {error: "rename.invalid-name"} |
Kompilacja przeglądarkowa nie ma własnego limitu czasu: uruchamiaj ją w workerze i kończ workera, gdy nie odpowie na czas. Odpowiedzi zawierają tekst z danych wejściowych, na przykład nazwy i dokumentację; przed umieszczeniem go na stronie zabezpiecz go (escape) jak każde dane od użytkownika.
Wersje i stabilność
version() zwraca wersję silnika i wersję interfejsu (abi). W obrębie wersji głównej operacje, pola i kody diagnostyczne nie są usuwane ani nie zmieniają znaczenia; mogą dochodzić nowe operacje, pola i kody, więc ignoruj to, czego nie znasz. Od wersji 2.0 każda nowa wersja główna jest zapowiadana z sześciomiesięcznym wyprzedzeniem.
Wypróbuj silnik na własnych modelach.
Wersja ewaluacyjna jest bezpłatna przez 60 dni i zawiera pełny przewodnik programisty oraz przykłady.