跳至:範例 · 進入點 · 請求與回應 · 診斷 · 錯誤 · 元素記錄 · 操作 · 變更集 · 限制
評估套件包含引擎、標準庫、完整的開發人員指南(每個操作都附真實的請求與回應)、診斷代碼清單,以及可執行的範例。引擎本身不在本頁。
範例:邊輸入邊檢查模型
最小的完整整合:一個含文字方塊的頁面,加上一個承載引擎的 worker。解開評估套件後即可直接執行:將兩個檔案放在 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 請求。每個請求帶有修訂編號 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
它載入引擎,並以一次呼叫回應每則訊息。迴路位址不需要授權權杖。
// 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}" }
引擎回應(token 與參照更新已縮短):
{
"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}。迴路來源不需要權杖。 |
適用於 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選擇操作。未知的 op 會回應{"error": "unknown-op"}。rev為選用:您送出的任何數字都會原樣傳回,發生錯誤時也一樣。用它將回應對應到計算時的狀態。- 回應是 JSON 物件。鍵的順序沒有意義;請忽略您不認識的鍵。
- 格式錯誤的 JSON、不是物件的請求,或缺少必要引數,會回應
{"error": "bad-request"}。 - 引擎絕不讀取檔案或存取網路。它所需的一切都在請求中、在以
library.load載入的庫中,或在文件工作階段中。
位移
每個位置(offset、range.from、range.to,以及編輯與來源對應的 from/to)都以呼叫端的單位計算:WebAssembly 建置中為 UTF-16 程式碼單位,與 JavaScript 字串及編輯器位移一致;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。 |
清單依位置排序。發生語法錯誤後,後續的語法診斷會等到剖析器再次讀到正確的 token 才出現,因此一個錯誤不會引發連鎖反應。
錯誤代碼
| 錯誤 | 操作 | 意義 |
|---|---|---|
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 建置 | 呼叫的時間配額已用完,或同時執行的呼叫過多。 |
元素記錄
文字會轉成元素記錄:一個將每個元素 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 | 字串 | Metaclass,例如 Package、PartDefinition、PartUsage、ConnectionUsage 或 TransitionUsage(SysML v2 的 metaclass 名稱)。必要。 |
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 | 物件 | 依 metaclass 而定:連接器端點、轉移的觸發與效果、匯入目標與篩選條件、註解文字、約束運算式等。 |
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 | qname,例如 ISQ::MassValue | {id},該名稱對應的庫元素 id。 |
lex | text | {tokens, diagnostics}:[kind, from, to] token 與詞法診斷。速度快;用於首次繪製。 |
roundtrip | text | {text, same, diagnostics}:由 token 重建的文字;詞法分析器的自我測試。 |
parse | text | {errors, diagnostics}:僅語法,不解析名稱。 |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}。編輯器的主要操作:帶語意種類(def、ref、unresolved)的 token、語法與語意診斷,以及參照更新。帶 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}:以項目的 insert 或 label 取代 from..to。 |
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,原始值保留在 xid。引擎不解讀之種類的元素會保留為不透明記錄,由 json_export 原封不動寫回,每個種類附一則 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"} |
瀏覽器建置本身沒有時間限制:請在 worker 中執行,並在它未及時回應時結束 worker。回應中含有來自輸入的文字,例如名稱與文件說明;放入頁面之前,請像處理任何使用者輸入一樣將其跳脫。
版本與穩定性
version() 回報引擎版本與介面版本(abi)。在同一主要版本內,操作、欄位與診斷代碼不會被移除或改變意義;可能會新增操作、欄位與代碼,因此請忽略您不認識的部分。自 2.0 版起,新的主要版本會提前六個月公告。