跳转到:示例 · 入口点 · 请求和应答 · 诊断 · 错误 · 元素记录 · 操作 · 变更集 · 限制
评估包包含引擎、标准库、为每个操作提供真实请求和应答的完整开发者指南、诊断代码列表,以及可运行的示例。引擎本身不在本页上。
示例:在输入时检查模型
最小的完整集成:一个带文本框的页面和一个承载引擎的 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}" }
引擎应答(令牌和引用更新已缩短):
{
"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。 |
列表按位置排序。出现语法错误后,后续的语法诊断会等到语法分析器再次读到有效令牌时才报告,因此一个错误不会引发连锁报错。
错误代码
| 错误 | 操作 | 含义 |
|---|---|---|
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 | 字符串 | 元类,例如 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 | 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}:用某个条目的 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,原始 id 保留在 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 版起,新的主版本会提前六个月公布。