Holarch Language Engine
مرجع واجهة 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.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. استدعه مرة واحدة لكل عامل. |
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}. ولا تحتاج أصول الاسترجاع المحلي إلى رمز. |
يكشف بناء الخادم لـ 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 سجلات لا يحتفظ بها هذا العامل؛ أرسل 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 | سلسلة نصية | الصنف الفوقي (metaclass)، مثل 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}: عناصر SysML v2 JSON (@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) وأنهِ العامل حين لا يجيب في الوقت المحدد. وتحتوي الإجابات على نص من المدخل، مثل الأسماء والتوثيق؛ فهرّبه كأي مدخل من المستخدم قبل وضعه في صفحة.
الإصدارات والاستقرار
يبلّغ version() عن إصدار المحرك وإصدار الواجهة (abi). وداخل الإصدار الرئيسي الواحد، لا تُزال العمليات والحقول ورموز التشخيص ولا يتغير معناها؛ ويمكن إضافة عمليات وحقول ورموز جديدة، فتجاهل ما لا تعرفه. وبدءًا من الإصدار 2.0، يُعلن عن الإصدار الرئيسي الجديد قبل ستة أشهر.
جرّب المحرك على نماذجك.
التقييم مجاني لمدة 60 يومًا ويشمل دليل المطوّر الكامل والأمثلة.