移動:例 · エントリーポイント · リクエストと応答 · 診断 · エラー · 要素レコード · 操作 · 変更セット · 制限
評価パッケージには、エンジン、標準ライブラリ、すべての操作について実際のリクエストと応答を載せた完全な開発者ガイド、診断コードの一覧、実行可能な例が含まれています。エンジン自体はこのページにはありません。
例:入力中にモデルをチェックする
最小限の完全な統合:テキストボックスのあるページと、エンジンをホストするワーカー。評価パッケージを展開すればそのまま動作します。両方のファイルを examples/00-quick-start/ に置き、パッケージのフォルダーをループバックアドレスで配信し、ページを開きます。
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 リクエストを 1 つ送信します。各リクエストはリビジョン番号 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.js
エンジンを読み込み、各メッセージに 1 回の呼び出しで応答します。ループバックアドレスではライセンストークンは不要です。
// 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は JavaScript の文字列インデックスと同じく UTF-16 コード単位です:text.slice(43, 46)は"Pmp"です。codeはリリース間で安定しています。評価パッケージには、すべてのコードについて英語のメッセージがあります(Pmp is not defined here. Check the spelling, or import its package.)。tokensは、ハイライト用の[kind, from, to]の 3 つ組です。
エントリーポイント
ブラウザーと Node.js では、エンジンは小さなグルースクリプトを伴う WebAssembly モジュールです。グルーはグローバルを 1 つ、wasm_bindgen を定義します。これは次のエクスポートを持つ非同期の初期化関数です。
| エクスポート | シグネチャ | 備考 |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | .wasm のバイト列、WebAssembly.Module、URL、または Response からモジュールをインスタンス化します。ワーカーごとに 1 回呼び出します。 |
call(request) | string → string | JSON リクエストを 1 つ実行し、JSON 応答を 1 つ返します。どのような入力文字列に対しても例外を投げません。内部障害の場合は RuntimeError を投げます。その後は新しいワーカーを開始してください。 |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}。unlock の前でも動作します。 |
heap_bytes() | () → number | エンジンの割り当てが現在保持しているバイト数。WebAssembly のメモリは増える一方なので、2 つを比較すると新しいワーカーでどれだけ節約できるかがわかります。unlock の前でも動作します。 |
notice() | () → string | 著作権表示。unlock の前でも動作します。 |
unlock(token) | string → string | ワーカーのオリジンに対してライセンストークンを適用し、{ok, …} または {ok: false, reason} を返します。ループバックのオリジンではトークンは不要です。 |
Enterprise ライセンスで利用できる Python 用のサーバービルドは、同じ JSON で call(request: str) -> str と version() -> str を公開しています。
リクエストと応答
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opで操作を選択します。不明な op には{"error": "unknown-op"}が返ります。revは任意です。送信した数値は、エラーの場合も含めて変更されずに返されます。応答を、それが計算された状態と対応付けるために使います。- 応答は JSON オブジェクトです。キーの順序に意味はありません。知らないキーは無視してください。
- 不正な形式の JSON、オブジェクトでないリクエスト、必須の引数の欠落には
{"error": "bad-request"}が返ります。 - エンジンはファイルやネットワークを読み取りません。必要なものはすべて、リクエスト内、
library.loadで読み込んだライブラリ内、またはドキュメントセッション内にあります。
オフセット
すべての位置(offset、range.from、range.to、および編集とソースマップの from/to)は呼び出し側の単位で数えます。WebAssembly ビルドでは JavaScript の文字列やエディターのオフセットに合わせた UTF-16 コード単位、Python ビルドでは Unicode コードポイントです。範囲は半開区間です。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。 |
リストは位置順に並べられています。構文エラーの後、パーサーが再び正しいトークンを読むまで後続の構文診断は保留されるため、1 つの誤りが連鎖的なエラーを生むことはありません。
エラーコード
| エラー | 操作 | 意味 |
|---|---|---|
bad-request | すべて | 不正な形式の JSON、オブジェクトでない、または必須の引数が欠落しているか型が誤っている。 |
unknown-op | すべて | このバージョンにはその操作がない。 |
limit.input-size | テキスト操作とレコード操作 | 8 MiB(UTF-8)を超えるテキスト、または合計 64 MiB を超えるライブラリファイル。 |
limit.nesting | レコード操作、json_import、v1_convert | 512 を超える深さのレコード(または SysML v1 要素)の所有者チェーン。 |
limit.elements | v1_convert | モデル内の要素とリストエントリーが 250,000 を超える。 |
limit.output-size | v1_convert | 変換後のテキストが 8 MiB を超える。 |
mirror-missing | analyze | mirrorKey が、このワーカーが保持していないレコードを指している。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 ビルド | 呼び出しの時間予算を使い切った、または同時に実行されている呼び出しが多すぎる。 |
要素レコード
テキストは要素レコードになります。各要素 ID をフラットなレコードに対応付ける JSON オブジェクトです。モデル操作はこの形式を受け取り、返します。
{
"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 | 文字列 | インポートした JSON から保持された ID。 |
fmt | オブジェクト | プリンター用のヒント。変更せずに保持するか、変更によって保存された綴りが誤りになる場合は削除してください。 |
参照は {ref, text, chain?, conj?} です。ref は対象の ID(未解決の間は null)、text は書かれたとおりの名前(修飾名 A::B またはフィーチャーチェーン a.b.c)、chain はチェーンの各セグメントの解決済み ID、conj: true は共役型(~P)を示します。
ID は小文字の UUID です。lower は doc 引数と各要素のパスから ID を導き出すため、同じテキストと doc からは同じ ID が得られます。sync と diff は既存の ID を保持し、新しい要素には seed から ID を与えます。ライブラリの要素は、どのバージョンでも同じ 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 | ISQ::MassValue などの qname | {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" でそれをチェックするため、モデル全体を 1 つのリクエストとしてメモリに置く必要はありません。{"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}:context から target に解決される最も短い名前。 |
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 への変更セットと、new の各要素が結果の中で持つ ID。 |
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}。UUID でない ID には UUID が与えられ、元の ID は xid に保持されます。エンジンが解釈しない種類の要素は不透明なレコードとして保持され、json_export はそれを変更せずに書き戻します。種類ごとに 1 つの json.kept-unsupported の注記が付きます。 |
v1_convert | model:お客様の統合が XMI から読み取った SysML v1 モデル; [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"} |
ブラウザービルド自体には時間制限がありません。ワーカーで実行し、時間内に応答しない場合はワーカーを終了してください。応答には名前やドキュメントなど入力からのテキストが含まれます。ページに挿入する前に、他のユーザー入力と同様にエスケープしてください。
バージョンと安定性
version() は、エンジンのバージョンとインターフェースのバージョン(abi)を報告します。メジャーバージョン内では、操作、フィールド、診断コードが削除されたり意味が変わったりすることはありません。新しい操作、フィールド、コードが追加されることはあるため、知らないものは無視してください。バージョン 2.0 以降、新しいメジャーバージョンは 6 か月前に告知します。