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 | Применяет токен лицензии для origin worker-а и отвечает {ok, …} или {ok: false, reason}. Origin-ам 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 | все | Для этого origin нет принятой лицензии. Приходит с 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 до 1000 символов, без управляющих символов | {error: "rename.invalid-name"} |
У браузерной сборки нет собственного ограничения времени: запускайте её в worker и завершайте worker, если он не отвечает вовремя. Ответы содержат текст из входных данных, например имена и документацию; экранируйте его, как любой пользовательский ввод, прежде чем помещать на страницу.
Версии и стабильность
version() сообщает версию движка и версию интерфейса (abi). В пределах основной версии операции, поля и коды диагностики не удаляются и не меняют смысла; новые операции, поля и коды могут добавляться, поэтому игнорируйте то, чего не знаете. Начиная с версии 2.0 о новой основной версии объявляется за шесть месяцев.
Попробуйте движок на собственных моделях.
Ознакомительный период бесплатный, 60 дней, и включает полное руководство разработчика и примеры.