바로 가기: 예제 · 진입점 · 요청과 응답 · 진단 · 오류 · 요소 레코드 · 작업 · 변경 세트 · 한도
평가 패키지에는 엔진, 표준 라이브러리, 모든 작업에 대한 실제 요청과 응답이 담긴 전체 개발자 가이드, 진단 코드 목록, 실행 가능한 예제가 들어 있습니다. 엔진 자체는 이 페이지에 없습니다.
예제: 입력하는 동안 모델 검사
가장 작은 완전한 통합으로, 텍스트 상자가 있는 페이지와 엔진을 호스팅하는 워커입니다. 평가 패키지의 압축을 풀면 그대로 실행됩니다. 두 파일을 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.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는 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]삼중 항목입니다.
진입점
브라우저와 Node.js에서 엔진은 작은 글루 스크립트가 있는 WebAssembly 모듈입니다. 글루는 전역 하나, wasm_bindgen을 정의합니다. 다음을 내보내는 비동기 초기화 함수입니다.
| 내보내기 | 시그니처 | 참고 |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | .wasm 바이트, WebAssembly.Module, URL 또는 Response에서 모듈을 인스턴스화합니다. 워커당 한 번 호출합니다. |
call(request) | string → string | JSON 요청 하나를 실행하고 JSON 응답 하나를 반환합니다. 어떤 입력 문자열에 대해서도 예외를 던지지 않습니다. 내부 결함이 생기면 RuntimeError를 던지며, 그 후에는 새 워커를 시작하십시오. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. unlock 전에도 작동합니다. |
heap_bytes() | () → number | 엔진의 할당이 현재 보유한 바이트 수. WebAssembly 메모리는 늘어나기만 하므로, 둘을 비교하면 새 워커가 얼마나 절약할지 알 수 있습니다. 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. |
목록은 위치순으로 정렬됩니다. 구문 오류가 발생하면 파서가 다시 올바른 토큰을 읽을 때까지 추가 구문 진단이 대기하므로, 실수 하나가 연쇄 오류를 만들지 않습니다.
오류 코드
| 오류 | 작업 | 의미 |
|---|---|---|
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 | 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}: 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"} |
브라우저 빌드에는 자체 시간 제한이 없습니다. 워커에서 실행하고, 제때 응답하지 않으면 워커를 종료하십시오. 응답에는 이름과 문서화 같은 입력의 텍스트가 포함됩니다. 페이지에 넣기 전에 다른 사용자 입력과 마찬가지로 이스케이프하십시오.
버전 및 안정성
version()은 엔진 버전과 인터페이스 버전(abi)을 보고합니다. 메이저 버전 안에서는 작업, 필드, 진단 코드가 제거되거나 의미가 바뀌지 않습니다. 새 작업, 필드, 코드는 추가될 수 있으므로 모르는 것은 무시하십시오. 버전 2.0부터 새 메이저 버전은 6개월 전에 발표됩니다.