Holarch Language Engine
Довідник API Language Engine
Публічний інтерфейс Holarch Language Engine: на вході один запит JSON, на виході одна відповідь JSON. На цій сторінці перелічено кожну операцію, її аргументи й відповідь, з одним невеликим прикладом. Вона описує Holarch Language Engine 2.0.
Перейти до: Приклад · Точки входу · Запити й відповіді · Діагностика · Помилки · Записи елементів · Операції · Набори змін · Обмеження
Ознайомлювальний пакет містить рушій, стандартну бібліотеку, повний посібник розробника зі справжнім запитом і відповіддю для кожної операції, перелік кодів діагностики та робочі приклади. Самого рушія на цій сторінці немає.
Приклад: перевірка моделі під час введення
Найменша повна інтеграція: сторінка з текстовим полем і worker, у якому працює рушій. Вона працює як є, щойно розпаковано ознайомлювальний пакет: покладіть обидва файли в examples/00-quick-start/, роздайте папку пакета на адресі loopback і відкрийте сторінку.
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/
Сторінка: index.html
Вона надсилає один запит analyze на кожну зміну. Кожен запит містить номер ревізії rev; рушій копіює його у відповідь, тож сторінка відкидає відповіді на запити, які вже замінила.
<!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
Він завантажує рушій і відповідає на кожне повідомлення одним викликом. Адреси loopback не потребують ліцензійного токена.
// 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
}
};
Запит і відповідь
Для зразкового тексту сторінка надсилає:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Рушій відповідає (токени й оновлення посилань скорочено):
{
"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": ["…"]
}
rangeвимірюється в кодових одиницях UTF-16, так само як індекси рядків JavaScript:text.slice(43, 46)— це"Pmp".codeсталий між випусками; ознайомлювальний пакет містить англійські повідомлення для кожного коду (Pmp is not defined here. Check the spelling, or import its package.).tokens— трійки[kind, from, to]для підсвічування.
Точки входу
У браузері та в Node.js рушій — це модуль WebAssembly з невеликим сполучним скриптом. Сполучний скрипт визначає одну глобальну змінну, wasm_bindgen: асинхронну функцію ініціалізації з такими експортами.
| Експорт | Сигнатура | Примітки |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Створює екземпляр модуля з байтів .wasm, WebAssembly.Module, URL або Response. Викликайте один раз на worker. |
call(request) | string → string | Виконує один запит JSON і повертає одну відповідь JSON. Ніколи не викидає виняток для будь-якого вхідного рядка. Внутрішній збій викидає RuntimeError; після нього запустіть новий worker. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Працює до unlock. |
heap_bytes() | () → number | Байти, які зараз утримують виділення пам’яті рушія. Пам’ять WebAssembly лише зростає; порівняйте обидва значення, щоб побачити, скільки заощадив би новий worker. Працює до unlock. |
notice() | () → string | Повідомлення про авторські права. Працює до unlock. |
unlock(token) | string → string | Застосовує ліцензійний токен для походження worker і відповідає {ok, …} або {ok: false, reason}. Походження loopback не потребують токена. |
Серверна збірка для Python, доступна з ліцензією Enterprise, надає call(request: str) -> str і version() -> str з тим самим JSON.
Запити й відповіді
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opвибирає операцію. На невідому операцію надходить відповідь{"error": "unknown-op"}.revнеобов’язковий: будь-яке надіслане число повертається без змін, також і з помилкою. Використовуйте його, щоб зіставляти відповіді зі станом, з якого їх обчислено.- Відповіді — це об’єкти JSON. Порядок ключів не має значення; ігноруйте невідомі ключі.
- На некоректний JSON, запит, що не є об’єктом, або відсутній обов’язковий аргумент надходить відповідь
{"error": "bad-request"}. - Рушій ніколи не читає файли й не звертається до мережі. Усе потрібне йому міститься в запиті, у бібліотеці, завантаженій через
library.load, або в сеансі документа.
Зсуви
Кожна позиція (offset, range.from, range.to, а також from/to редагувань і карт вихідного коду) рахується в одиницях викликача: кодових одиницях UTF-16 у збірці WebAssembly, що відповідає рядкам JavaScript і зсувам редактора, та кодових точках Unicode у збірці Python. Діапазони напіввідкриті; діапазон, у якому from дорівнює to, позначає позицію, наприклад місце, де бракує ;.
Діагностика
{
"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"
}
| Поле | Наявне | Значення |
|---|---|---|
code | завжди | Сталий код, family.rule. Ознайомлювальний пакет перелічує кожен код з його значенням і виправленням. |
severity | завжди, крім json_import | "error", "warning" або "info" (примітка, яка не потребує виправлення, наприклад текстове подання мовою, яку рушій не перевіряє). |
range | текстові операції | Місце в тексті. Операції з моделлю, як-от check, не мають тексту й діапазону. |
args | завжди | Рядкові значення для повідомлення (name, expected, found, …). Може бути порожнім. |
elementId | семантична діагностика | Елемент, перевірка якого її спричинила. |
field | часто | Поле запису, якого це стосується (typedBy, value, body.source, …). |
doc | семантична діагностика analyze | Значення doc із запиту або null. |
Списки впорядковано за позицією. Після синтаксичної помилки подальша синтаксична діагностика чекає, доки парсер знову прочитає коректний токен, тож одна помилка не спричиняє каскаду.
Коди помилок
| Помилка | Операції | Значення |
|---|---|---|
bad-request | усі | Некоректний JSON, не об’єкт або обов’язковий аргумент відсутній чи має неправильний тип. |
unknown-op | усі | У цій версії такої операції немає. |
limit.input-size | операції з текстом і записами | Текст понад 8 MiB (UTF-8) або файли бібліотеки сумарно понад 64 MiB. |
limit.nesting | операції із записами, json_import, v1_convert | Ланцюжок власників запису (або елемента SysML v1) глибший за 512. |
limit.elements | v1_convert | Понад 250,000 елементів і записів списків у моделі. |
limit.output-size | v1_convert | Перетворений текст перевищив би 8 MiB. |
mirror-missing | analyze | mirrorKey називає записи, яких цей worker не має; надішліть records знову. |
session-missing | check | base не є збереженим сеансом перевірки; надішліть усю модель знову з новим ключем. |
not-found | shortest_name | target немає в записах або бібліотеці. |
apply.<reason> | apply | Зміна не відповідає записам, наприклад apply.id-used або apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | Зсув не припадає на ім’я, ім’я належить бібліотеці або нове ім’я неприпустиме. |
feature-not-licensed | v1_convert | Операція належить до доповнення, яке не входить до ліцензії. Надходить із feature і message. |
not-licensed | усі | Немає прийнятої ліцензії для цього походження. Надходить із message. |
limit.time, busy | Збірка Python | Вичерпано бюджет часу виклику або одночасно виконується забагато викликів. |
Записи елементів
Текст стає записами елементів: об’єктом JSON, що зіставляє кожен id елемента з плоским записом. Операції з моделлю приймають і повертають цей формат.
{
"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" }
}
| Поле | Форма | Значення |
|---|---|---|
type | рядок | Метаклас, як-от Package, PartDefinition, PartUsage, ConnectionUsage або TransitionUsage (назви метакласів SysML v2). Обов’язкове. |
owner | id або null | Елемент-власник; null означає верхній рівень. Обов’язкове. |
order | рядок | Позиція серед членів власника. Порівнюйте як звичайні рядки, потім за id. Обов’язкове. |
role | рядок | Вид членства, якщо це не звичайний член: subject, actor, require, verify, return, entry, do, exit, then та інші. |
name, shortName | рядок | Як оголошено, без лапок. |
visibility | рядок | public, private або protected, якщо записано. |
flags | об’єкт | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel та інші (зберігається лише true); direction: in, out або inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | масив посилань | Зв’язки. |
multiplicity | {text} | Межі, як записано ("0..*"). |
value | {text, kind, default?} | kind — це "=" або ":="; text — вираз, як його записано. |
body | об’єкт | Залежно від метакласу: кінці з’єднувачів, тригери й ефекти переходів, цілі та фільтри імпорту, текст коментарів, вирази обмежень тощо. |
doc | рядок | Текст першого коментаря doc. |
xid, mid, docId | рядок | Id, збережені з імпортованого JSON. |
fmt | об’єкт | Підказки для друку тексту. Залиште без змін або видаліть, якщо ваша зміна робить збережене написання неправильним. |
Посилання мають вигляд {ref, text, chain?, conj?}: ref — id цілі (null, доки не розв’язано), text — ім’я, як його записано (кваліфіковане ім’я A::B або ланцюжок властивостей a.b.c), chain — розв’язаний id кожного сегмента ланцюжка, а conj: true позначає спряжений тип (~P).
Id — це UUID у нижньому регістрі. lower виводить їх з аргументу doc і шляху кожного елемента, тож той самий текст і doc дають ті самі id. sync і diff зберігають наявні id і надають новим елементам id з вашого seed. Елементи бібліотеки мають однакові id у кожній версії (lib_id).
Операції
Аргументи у квадратних дужках необов’язкові. Кожен запит може містити rev.
| Операція | Аргументи | Відповідь |
|---|---|---|
version | — | {core, abi, records, checkParts}: records — ревізія формату записів; checkParts повідомляє, що check приймає модель сеансу частинами. |
library.load | files: [{path, text}], файли бібліотеки .sysml і .kerml у будь-якому порядку (не більше 64 MiB) | {files, elements, skipped, packages}. Замінює бібліотеку й очищує всі сеанси документів. |
library.status | — | {files, elements} завантаженої бібліотеки. |
lib_id | qname, наприклад ISQ::MassValue | {id}, id елемента бібліотеки для цього імені. |
lex | text | {tokens, diagnostics}: токени [kind, from, to] і лексична діагностика. Швидко; для першого відображення. |
roundtrip | text | {text, same, diagnostics}: текст, відновлений з його токенів; самоперевірка лексера. |
parse | text | {errors, diagnostics}: лише синтаксис, без розв’язання імен. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. Основна операція редактора: токени із семантичними видами (def, ref, unresolved), синтаксична й семантична діагностика та оновлення посилань. З ключем doc рушій зберігає сеанс і повторно перевіряє лише те, чого може сягнути редагування; records розв’язують імена відносно решти моделі. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: записи елементів з нерозв’язаними посиланнями, id верхнього рівня в порядку тексту та члени, пропущені через синтаксичні помилки. |
check | records; [session] або [session], base, changes; [load] | {refs, diagnostics}: розв’язана ціль кожного посилання, збережений ref якого відрізняється, і діагностика з elementId та field. З ключем session рушій зберігає модель; пізніший запит називає її як base лише зі змінами changes ({id: record or null}), і рушій повторно перевіряє лише пакети, яких можуть сягнути зміни, з тією самою відповіддю, що й повна перевірка. load: "part" надсилає велику модель кількома запитами, а load: "end" перевіряє її, тож уся модель ніколи не мусить бути в пам’яті одним запитом. {"op": "check.drop"} звільняє збережену модель. |
evaluate | records; [ids] | {values}: для кожного id елемента значення {kind, text, …}, де kind — це number, quantity (з unit і dimension), boolean, string, unit, sequence, element або unknown. Показуйте text. |
analyze_case | records; [ids] | {cases, requirements}: кожен satisfy з його статусом (satisfied, violated, not-applicable, unknown) і значеннями обмежень, а також кожен випадок аналізу й верифікації з його результатом. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …} або {elementId: null} поза іменем. |
definition | як hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | як hover | {from, to, items}: замініть from..to на insert або label елемента. |
rename | як hover, плюс name | {elementId, changes}: [{from, to, insert}] для кожного входження в тексті. |
shortest_name | records, target; [context] | {text}: найкоротше ім’я, що розв’язується в target з context. |
print_records | records; [roots], [dialect] | {text}. Незмінені елементи друкуються байт у байт. |
canon_lines | records або text; [roots], [dialect], [per], [ids] | {lines, bytes}: розмір моделі в канонічних рядках, тобто рядках тексту, який рушій друкує для неї без документації, коментарів і порожніх рядків, тож кількість не залежить від того, як текст було написано. З per — частка кожного елемента; з ids — частки лише цих елементів, щоб підтримувати кількість актуальною після зміни. |
print | records; [root], [text] | {text, map, edits?}: текст, карта вихідного коду [{id, from, to}] і редагування, що перетворюють наданий текст на новий. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: набір змін, який узгоджує записи з текстом, зберігаючи наявні id. З apply: true натомість повертаються записи із застосованим набором змін ({count, diagnostics, notApplied, roots, records}), що потребує менше пам’яті для великого тексту. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: чернетка тексту, об’єднана зі змінами моделі, зробленими тим часом. |
diff | old, new; [base], [seed] | {changes, ids}: набір змін від old до new і id, який кожен елемент new має в результаті. |
apply | records, changes | {records} із застосованими змінами або {error: "apply.<reason>"}. |
edits | old, new (рядки) | {edits}: мінімальні заміни з урахуванням рядків. |
json_export | records; [ext] | {elements}: елементи SysML v2 JSON (@id, @type), зокрема елементи зв’язків. З ext (за замовчуванням) кожен елемент містить те, що потрібно json_import, щоб точно відновити записи. |
json_import | elements: масив, {elements: […]} або версії даних API | {records, diagnostics}. Id, які не є UUID, отримують UUID, а оригінал зберігається в xid. Елементи видів, які рушій не інтерпретує, зберігаються як непрозорі записи, які json_export записує назад без змін, з однією приміткою json.kept-unsupported на кожен вид. |
v1_convert | model: модель SysML v1, прочитана з XMI вашою інтеграцією; [check], [items] | {text, report, diagnostics?, library?}: текст SysML v2 і звіт про те, що перетворено, наближено або відкинуто. Частина доповнення для міграції, що ліцензується окремо. |
Набори змін
sync і diff повертають, а apply приймає впорядкований масив змін. Створення й переміщення йдуть у порядку документа, власники перед членами; вилучення йдуть останніми.
| Зміна | Значення |
|---|---|
{op: "create", id, fields, after?, before?} | Новий елемент, розміщений після або перед сусіднім елементом, або останнім. |
{op: "update", id, patch} | Зміни полів; null видаляє поле. Ніколи не змінює owner чи order. |
{op: "move", id, owner, after?, before?} | Новий власник або позиція. |
{op: "remove", ids} | Вилучає елементи й усе, чим вони володіють. |
Обмеження
Понад обмеження рушій відповідає діагностикою або кодом помилки, ніколи не зависає й не аварійно завершується. Кожна операція триває пропорційно своїм вхідним даним.
| Обмеження | Значення | Понад обмеження |
|---|---|---|
| Розмір тексту | 8 MiB (UTF-8) | limit.input-size |
| Довжина рядка | 64 KiB (UTF-8) | limit.line-length для кожного довгого рядка |
| Вкладеність тіл | 256 рівнів | limit.nesting; глибша частина пропускається |
| Вкладеність виразів | 512 рівнів | limit.expression-depth |
| Ланцюжок власників запису | 512 рівнів | {error: "limit.nesting"} |
| Файли бібліотеки, разом | 64 MiB | {error: "limit.input-size"} |
| Імпорт JSON | 500,000 елементів | json.too-many-elements; решта не читається |
Модель SysML v1 (v1_convert) | 250,000 елементів і записів списків; ланцюжки власників 512 рівнів; текст 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Нове ім’я в rename | Від 1 до 1,000 символів, без керівних символів | {error: "rename.invalid-name"} |
Браузерна збірка не має власного обмеження часу: запускайте її у worker і завершуйте worker, якщо він не відповідає вчасно. Відповіді містять текст із вхідних даних, як-от імена й документацію; екрануйте його, як будь-які дані користувача, перш ніж вставляти на сторінку.
Версії та стабільність
version() повідомляє версію рушія та версію інтерфейсу (abi). У межах основної версії операції, поля й коди діагностики не вилучаються й не змінюють значення; можуть додаватися нові операції, поля й коди, тож ігноруйте те, чого не знаєте. Починаючи з версії 2.0, про нову основну версію оголошують за шість місяців.
Випробуйте рушій на власних моделях.
Ознайомлювальна версія безкоштовна протягом 60 днів і містить повний посібник розробника та приклади.