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 | מחיל אסימון רישיון עבור המקור של ה-worker ועונה {ok, …}, או {ok: false, reason}. מקורות 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 | כולן | אין רישיון מאושר עבור המקור הזה. מגיעה עם message. |
limit.time, busy | גרסת Python | תקציב הזמן של הקריאה נגמר, או שיותר מדי קריאות רצות בו-זמנית. |
רשומות רכיבים
טקסט הופך לרשומות רכיבים: אובייקט 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 | מזהה או null | הרכיב הבעלים; null הוא רמה עליונה. חובה. |
order | מחרוזת | המיקום בין החברים של הבעלים. ההשוואה כמחרוזות פשוטות, ואז לפי מזהה. חובה. |
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 מיובא. |
fmt | אובייקט | רמזים למדפיס. יש להשאיר ללא שינוי, או למחוק כשהשינוי שלכם הופך את האיות השמור לשגוי. |
הפניות הן {ref, text, chain?, conj?}: ref הוא מזהה היעד (null כל עוד לא נפתרה), text השם כפי שנכתב (שם מלא A::B או שרשרת מאפיינים a.b.c), chain המזהה שנפתר של כל מקטע בשרשרת, ו-conj: true מסמן טיפוס מצומד (~P).
מזהים הם UUID באותיות קטנות. lower גוזר אותם מהארגומנט doc ומהנתיב של כל רכיב, כך שאותו טקסט ואותו doc נותנים אותם מזהים. sync ו-diff שומרים על מזהים קיימים ונותנים לרכיבים חדשים מזהים מה-seed שלכם. לרכיבי הספרייה יש אותם מזהים בכל גרסה (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}, מזהה רכיב הספרייה עבור השם הזה. |
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}: רשומות רכיבים עם הפניות שלא נפתרו, המזהים ברמה העליונה בסדר הטקסט, וחברים שדולגו בגלל שגיאות תחביר. |
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}: לכל מזהה רכיב ערך {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}: ערכת השינויים שמתאימה את הרשומות לטקסט, תוך שמירה על המזהים הקיימים. עם 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 בתוצאה. |
apply | records, changes | {records} לאחר החלת השינויים, או {error: "apply.<reason>"}. |
edits | old, new (מחרוזות) | {edits}: החלפות מינימליות לפי שורות. |
json_export | records; [ext] | {elements}: רכיבי JSON של SysML v2 (@id, @type), כולל רכיבי קשר. עם ext (ברירת המחדל) כל רכיב נושא את מה ש-json_import צריך כדי לשחזר את הרשומות במדויק. |
json_import | elements: מערך, {elements: […]}, או גרסאות נתונים של API | {records, diagnostics}. מזהים שאינם 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 עד 1,000 תווים, ללא תווי בקרה | {error: "rename.invalid-name"} |
לגרסת הדפדפן אין מגבלת זמן משלה: יש להריץ אותה ב-worker ולסיים את ה-worker כשהוא אינו עונה בזמן. התשובות מכילות טקסט מהקלט, כגון שמות ותיעוד; יש לבצע לו escape כמו לכל קלט משתמש לפני שמכניסים אותו לדף.
גרסאות ויציבות
version() מדווח על גרסת המנוע ועל גרסת הממשק (abi). בתוך גרסה ראשית, פעולות, שדות וקודי אבחון אינם מוסרים ומשמעותם אינה משתנה; אפשר להוסיף פעולות, שדות וקודים חדשים, ולכן יש להתעלם ממה שאינו מוכר. מגרסה 2.0 ואילך, גרסה ראשית חדשה מוכרזת שישה חודשים מראש.
אפשר לנסות את המנוע על המודלים שלכם.
ההערכה בחינם למשך 60 יום וכוללת את מדריך המפתחים המלא ואת הדוגמאות.