Holarch Language Engine
Language Engine API başvurusu
Holarch Language Engine'in genel arayüzü: bir JSON isteği girer, bir JSON yanıtı çıkar. Bu sayfa her işlemi, bağımsız değişkenlerini ve yanıtını küçük bir örnekle listeler. Holarch Language Engine 2.0'ı açıklar.
Şuraya git: Örnek · Giriş noktaları · İstekler ve yanıtlar · Tanılamalar · Hatalar · Öğe kayıtları · İşlemler · Değişiklik kümeleri · Sınırlar
Değerlendirme paketi motoru, standart kitaplığı, her işlem için gerçek bir istek ve yanıt içeren tam geliştirici kılavuzunu, tanılama kodlarının listesini ve çalıştırılabilir örnekleri içerir. Motorun kendisi bu sayfada değildir.
Örnek: yazarken bir modeli denetleme
En küçük eksiksiz entegrasyon: metin kutulu bir sayfa ve motoru barındıran bir worker. Değerlendirme paketi açıldığında olduğu gibi çalışır: iki dosyayı examples/00-quick-start/ klasörüne koyun, paket klasörünü loopback adresinde sunun ve sayfayı açın.
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/
Sayfa: index.html
Her değişiklik için bir analyze isteği gönderir. Her istek bir revizyon numarası rev taşır; motor bunu yanıta kopyalar, böylece sayfa yerine yenisini gönderdiği isteklerin yanıtlarını atar.
<!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
Motoru yükler ve her iletiyi tek bir çağrıyla yanıtlar. Loopback adresleri lisans belirteci gerektirmez.
// 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
}
};
İstek ve yanıt
Örnek metin için sayfa şunu gönderir:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Motor şöyle yanıtlar (belirteçler ve başvuru güncellemeleri kısaltılmıştır):
{
"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 dize dizinleriyle aynı şekilde UTF-16 kod birimleriyle ifade edilir:text.slice(43, 46)değeri"Pmp"olur.codesürümler arasında sabittir; değerlendirme paketinde her kod için İngilizce iletiler vardır (Pmp is not defined here. Check the spelling, or import its package.).tokens, vurgulama için[kind, from, to]üçlüleridir.
Giriş noktaları
Tarayıcıda ve Node.js'te motor, küçük bir yapıştırıcı betiği olan bir WebAssembly modülüdür. Yapıştırıcı tek bir genel değişken tanımlar, wasm_bindgen: bu dışa aktarımlara sahip zaman uyumsuz bir başlatma işlevi.
| Dışa aktarma | İmza | Notlar |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Modülü .wasm baytlarından, bir WebAssembly.Module'den, bir URL'den veya bir Response'tan örnekler. Worker başına bir kez çağırın. |
call(request) | string → string | Bir JSON isteğini çalıştırır ve bir JSON yanıtı döndürür. Hiçbir girdi dizesi için istisna fırlatmaz. Dahili bir arıza RuntimeError fırlatır; bundan sonra yeni bir worker başlatın. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. unlock öncesinde de çalışır. |
heap_bytes() | () → number | Motorun ayırmalarının şu anda tuttuğu bayt sayısı. WebAssembly belleği yalnızca büyür; yeni bir worker'ın ne kadar tasarruf sağlayacağını görmek için ikisini karşılaştırın. unlock öncesinde de çalışır. |
notice() | () → string | Telif hakkı bildirimi. unlock öncesinde de çalışır. |
unlock(token) | string → string | Worker'ın kaynağı için bir lisans belirteci uygular ve {ok, …} veya {ok: false, reason} yanıtını verir. Loopback kaynakları belirteç gerektirmez. |
Enterprise lisansıyla sunulan Python için sunucu derlemesi, aynı JSON ile call(request: str) -> str ve version() -> str sağlar.
İstekler ve yanıtlar
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opişlemi seçer. Bilinmeyen bir op{"error": "unknown-op"}yanıtını verir.revisteğe bağlıdır: gönderdiğiniz her sayı, hata durumunda da değişmeden geri gelir. Yanıtları hesaplandıkları durumla eşleştirmek için kullanın.- Yanıtlar JSON nesneleridir. Anahtar sırasının bir anlamı yoktur; bilmediğiniz anahtarları yok sayın.
- Hatalı biçimlendirilmiş JSON, nesne olmayan bir istek veya eksik bir zorunlu bağımsız değişken
{"error": "bad-request"}yanıtını verir. - Motor hiçbir zaman dosya veya ağ okumaz. İhtiyaç duyduğu her şey istekte,
library.loadile yüklenen kitaplıkta veya bir belge oturumundadır.
Konumlar
Her konum (offset, range.from, range.to ve düzenlemelerle kaynak eşlemelerinin from/to değerleri) çağıranın birimleriyle sayılır: WebAssembly derlemesinde JavaScript dizeleri ve düzenleyici konumlarıyla eşleşen UTF-16 kod birimleri, Python derlemesinde Unicode kod noktaları. Aralıklar yarı açıktır; from değeri to değerine eşit olan bir aralık, örneğin bir ; işaretinin eksik olduğu yer gibi bir konumu belirtir.
Tanılamalar
{
"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"
}
| Alan | Bulunur | Anlamı |
|---|---|---|
code | her zaman | Sabit kod, family.rule. Değerlendirme paketi her kodu anlamı ve düzeltmesiyle listeler. |
severity | her zaman, json_import dışında | "error", "warning" veya "info" (düzeltilecek bir şey olmayan bir not, örneğin motorun denetlemediği bir dildeki metinsel gösterim). |
range | metin işlemleri | Metindeki yeri. check gibi model işlemlerinin metni ve aralığı yoktur. |
args | her zaman | İleti için dize değerleri (name, expected, found, …). Boş olabilir. |
elementId | anlamsal tanılamalar | Tanılamayı denetimi oluşturan öğe. |
field | çoğunlukla | İlgili kayıt alanı (typedBy, value, body.source, …). |
doc | analyze anlamsal tanılamaları | İsteğin doc değeri veya null. |
Listeler konuma göre sıralanır. Bir sözdizimi hatasından sonra, ayrıştırıcı yeniden geçerli bir belirteç okuyana kadar başka sözdizimi tanılamaları bekletilir; böylece tek bir hata zincirleme hatalara yol açmaz.
Hata kodları
| Hata | İşlemler | Anlamı |
|---|---|---|
bad-request | tümü | Hatalı biçimlendirilmiş JSON, nesne olmayan bir istek veya eksik ya da yanlış türde bir zorunlu bağımsız değişken. |
unknown-op | tümü | Bu sürümde böyle bir işlem yok. |
limit.input-size | metin ve kayıt işlemleri | 8 MiB'ı (UTF-8) aşan bir metin veya toplamda 64 MiB'ı aşan kitaplık dosyaları. |
limit.nesting | kayıt işlemleri, json_import, v1_convert | 512'den derin bir kayıt (veya SysML v1 öğesi) sahip zinciri. |
limit.elements | v1_convert | Modelde 250.000'den fazla öğe ve liste girdisi. |
limit.output-size | v1_convert | Dönüştürülen metin 8 MiB'ı aşar. |
mirror-missing | analyze | mirrorKey, bu worker'ın tutmadığı kayıtları adlandırıyor; records değerini yeniden gönderin. |
session-missing | check | base, tutulan denetim oturumu değil; modelin tamamını yeni bir anahtarla yeniden gönderin. |
not-found | shortest_name | target kayıtlarda veya kitaplıkta yok. |
apply.<reason> | apply | Bir değişiklik kayıtlara uymuyor, örneğin apply.id-used veya apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | Konum bir ad üzerinde değil, ad kitaplığa ait veya yeni ad geçerli değil. |
feature-not-licensed | v1_convert | İşlem, lisansın içermediği bir eklentiye ait. feature ve message ile birlikte gelir. |
not-licensed | tümü | Bu kaynak için kabul edilmiş lisans yok. message ile birlikte gelir. |
limit.time, busy | Python derlemesi | Çağrının süre bütçesi doldu veya aynı anda çok fazla çağrı çalışıyor. |
Öğe kayıtları
Metin öğe kayıtlarına dönüşür: her öğe kimliğini düz bir kayda eşleyen bir JSON nesnesi. Model işlemleri bu biçimi alır ve döndürür.
{
"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" }
}
| Alan | Yapı | Anlamı |
|---|---|---|
type | dize | Metasınıf, örneğin Package, PartDefinition, PartUsage, ConnectionUsage veya TransitionUsage (SysML v2 metasınıf adları). Zorunlu. |
owner | kimlik veya null | Sahip öğe; null en üst düzeydir. Zorunlu. |
order | dize | Sahibin üyeleri arasındaki konum. Önce düz dize olarak, sonra kimliğe göre karşılaştırın. Zorunlu. |
role | dize | Sıradan bir üye olmadığında üyelik türü: subject, actor, require, verify, return, entry, do, exit, then ve diğerleri. |
name, shortName | dize | Bildirildiği gibi, tırnak işaretleri olmadan. |
visibility | dize | Yazıldığında public, private veya protected. |
flags | nesne | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel ve diğerleri (yalnızca true saklanır); direction: in, out veya inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | başvuru dizisi | İlişkiler. |
multiplicity | {text} | Yazıldığı gibi sınırlar ("0..*"). |
value | {text, kind, default?} | kind değeri "=" veya ":="; text yazıldığı haliyle ifadedir. |
body | nesne | Metasınıfa göre: bağlayıcı uçları, geçiş tetikleyicileri ve etkileri, içe aktarma hedefleri ve filtreleri, yorum metni, kısıt ifadeleri vb. |
doc | dize | İlk doc yorumunun metni. |
xid, mid, docId | dize | İçe aktarılan JSON'dan korunan kimlikler. |
fmt | nesne | Yazdırıcı ipuçları. Değiştirmeden bırakın veya değişikliğiniz saklanan yazımı yanlış hale getiriyorsa silin. |
Başvurular {ref, text, chain?, conj?} biçimindedir: ref hedef kimliktir (çözümlenmemişken null), text yazıldığı haliyle addır (nitelikli bir ad A::B veya bir özellik zinciri a.b.c), chain her zincir parçasının çözümlenmiş kimliğidir ve conj: true eşlenik bir türü (~P) belirtir.
Kimlikler küçük harfli UUID'lerdir. lower bunları doc bağımsız değişkeninden ve her öğenin yolundan türetir; böylece aynı metin ve doc aynı kimlikleri verir. sync ve diff mevcut kimlikleri korur ve yeni öğelere seed değerinizden kimlik verir. Kitaplık öğeleri her sürümde aynı kimliklere sahiptir (lib_id).
İşlemler
Köşeli parantez içindeki bağımsız değişkenler isteğe bağlıdır. Her istek rev taşıyabilir.
| İşlem | Bağımsız değişkenler | Yanıt |
|---|---|---|
version | — | {core, abi, records, checkParts}: records kayıt biçimi revizyonudur; checkParts, check işleminin bir oturumun modelini parçalar halinde aldığını belirtir. |
library.load | files: [{path, text}], herhangi bir sırada .sysml ve .kerml kitaplık dosyaları (en fazla 64 MiB) | {files, elements, skipped, packages}. Kitaplığı değiştirir ve tüm belge oturumlarını temizler. |
library.status | — | Yüklenen kitaplığın {files, elements} değerleri. |
lib_id | qname, örneğin ISQ::MassValue | {id}, o ada ait kitaplık öğesi kimliği. |
lex | text | {tokens, diagnostics}: [kind, from, to] belirteçleri ve sözcüksel tanılamalar. Hızlıdır; ilk çizim için. |
roundtrip | text | {text, same, diagnostics}: belirteçlerinden yeniden oluşturulan metin; bir sözcük çözümleyici öz testi. |
parse | text | {errors, diagnostics}: yalnızca sözdizimi, ad çözümleme yok. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. Düzenleyicinin ana işlemi: anlamsal türleri olan belirteçler (def, ref, unresolved), sözdizimi ve anlamsal tanılamalar ve başvuru güncellemeleri. Bir doc anahtarıyla motor bir oturum tutar ve yalnızca bir düzenlemenin etkileyebileceği kısmı yeniden denetler; records, adları modelin geri kalanına göre çözümler. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: çözümlenmemiş başvurulu öğe kayıtları, metin sırasındaki en üst düzey kimlikler ve sözdizimi hataları nedeniyle atlanan üyeler. |
check | records; [session] veya [session], base, changes; [load] | {refs, diagnostics}: saklanan ref değerinden farklı olan her başvurunun çözümlenmiş hedefi ve elementId ile field içeren tanılamalar. Bir session anahtarıyla motor modeli tutar; sonraki bir istek onu base olarak yalnızca changes ({id: record or null}) ile adlandırır ve motor yalnızca değişikliklerin etkileyebileceği paketleri yeniden denetler; yanıt tam denetimle aynıdır. load: "part" büyük bir modeli birkaç istekte gönderir ve load: "end" onu denetler; böylece modelin tamamının hiçbir zaman tek bir istek olarak bellekte olması gerekmez. {"op": "check.drop"} tutulan modeli serbest bırakır. |
evaluate | records; [ids] | {values}: öğe kimliği başına bir değer {kind, text, …}; burada kind değeri number, quantity (unit ve dimension ile), boolean, string, unit, sequence, element veya unknown olur. text değerini gösterin. |
analyze_case | records; [ids] | {cases, requirements}: durumu (satisfied, violated, not-applicable, unknown) ve kısıt değerleriyle her satisfy ve sonucuyla her analiz ve doğrulama durumu. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …} veya bir ad dışında {elementId: null}. |
definition | hover gibi | {elementId, qualifiedName, range?, doc?, library?}. |
complete | hover gibi | {from, to, items}: from..to aralığını bir öğenin insert veya label değeriyle değiştirin. |
rename | hover gibi, ayrıca name | {elementId, changes}: metindeki her geçiş için [{from, to, insert}]. |
shortest_name | records, target; [context] | {text}: context konumundan target hedefine çözümlenen en kısa ad. |
print_records | records; [roots], [dialect] | {text}. Değişmemiş öğeler bayt bayt aynı yazdırılır. |
canon_lines | records veya text; [roots], [dialect], [per], [ids] | {lines, bytes}: modelin kanonik satır cinsinden boyutu, yani motorun model için belgeler, yorumlar ve boş satırlar olmadan yazdırdığı metnin satırları; böylece sayı metnin nasıl yazıldığına bağlı değildir. per ile her öğenin payı; ids ile, bir değişiklikten sonra sayıyı güncel tutmak için yalnızca o öğelerin payları. |
print | records; [root], [text] | {text, map, edits?}: metin, bir kaynak eşlemesi [{id, from, to}] ve verilen metni yenisine dönüştüren düzenlemeler. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: mevcut kimlikleri koruyarak kayıtları metinle eşleştiren değişiklik kümesi. apply: true ile bunun yerine değişiklik kümesi uygulanmış kayıtlar ({count, diagnostics, notApplied, roots, records}); büyük bir metin için daha az bellek gerektirir. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: bu arada yapılan model değişiklikleriyle birleştirilmiş bir metin taslağı. |
diff | old, new; [base], [seed] | {changes, ids}: old değerinden new değerine değişiklik kümesi ve new içindeki her öğenin sonuçtaki kimliği. |
apply | records, changes | Değişiklikler uygulanmış {records} veya {error: "apply.<reason>"}. |
edits | old, new (dizeler) | {edits}: satırları dikkate alan en küçük değiştirmeler. |
json_export | records; [ext] | {elements}: ilişki öğeleri dahil SysML v2 JSON öğeleri (@id, @type). ext ile (varsayılan) her öğe, json_import işleminin kayıtları tam olarak geri yüklemesi için gerekenleri taşır. |
json_import | elements: bir dizi, {elements: […]} veya API veri sürümleri | {records, diagnostics}. UUID olmayan kimliklere UUID verilir, özgün kimlik xid içinde korunur. Motorun yorumlamadığı türlerdeki öğeler, json_export işleminin değiştirmeden geri yazdığı opak kayıtlar olarak korunur; her tür için bir json.kept-unsupported notu eklenir. |
v1_convert | model: entegrasyonunuzun XMI'dan okuduğu bir SysML v1 modeli; [check], [items] | {text, report, diagnostics?, library?}: SysML v2 metni ve neyin dönüştürüldüğünü, yaklaşık olarak aktarıldığını veya atıldığını gösteren bir rapor. Ayrıca lisanslanan geçiş eklentisinin parçasıdır. |
Değişiklik kümeleri
sync ve diff sıralı bir değişiklik dizisiyle yanıt verir, apply da böyle bir dizi alır. Oluşturmalar ve taşımalar belge sırasıyla, sahipler üyelerden önce gelir; kaldırmalar en sonda gelir.
| Değişiklik | Anlamı |
|---|---|
{op: "create", id, fields, after?, before?} | Bir kardeş öğenin önüne veya arkasına ya da en sona yerleştirilen yeni bir öğe. |
{op: "update", id, patch} | Alan değişiklikleri; null bir alanı siler. owner veya order değerini hiçbir zaman değiştirmez. |
{op: "move", id, owner, after?, before?} | Yeni bir sahip veya konum. |
{op: "remove", ids} | Öğeleri ve sahip oldukları her şeyi kaldırır. |
Sınırlar
Bir sınır aşıldığında motor bir tanılama veya hata koduyla yanıt verir; hiçbir zaman takılmaz veya çökmez. Her işlem girdisiyle orantılı süre alır.
| Sınır | Değer | Sınır aşıldığında |
|---|---|---|
| Metin boyutu | 8 MiB (UTF-8) | limit.input-size |
| Satır uzunluğu | 64 KiB (UTF-8) | Her uzun satır için limit.line-length |
| Gövde iç içeliği | 256 düzey | limit.nesting; daha derin kısım atlanır |
| İfade iç içeliği | 512 düzey | limit.expression-depth |
| Kayıt sahip zinciri | 512 düzey | {error: "limit.nesting"} |
| Kitaplık dosyaları, toplam | 64 MiB | {error: "limit.input-size"} |
| JSON içe aktarma | 500.000 öğe | json.too-many-elements; geri kalanı okunmaz |
SysML v1 modeli (v1_convert) | 250.000 öğe ve liste girdisi; sahip zincirleri 512 düzey; metin 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
rename içindeki yeni ad | 1 ile 1.000 karakter arası, denetim karakteri yok | {error: "rename.invalid-name"} |
Tarayıcı derlemesinin kendine ait bir süre sınırı yoktur: onu bir worker'da çalıştırın ve zamanında yanıt vermezse worker'ı sonlandırın. Yanıtlar, adlar ve belgeler gibi girdiden gelen metinler içerir; bir sayfaya koymadan önce bunları herhangi bir kullanıcı girdisi gibi kaçışlayın.
Sürümler ve kararlılık
version(), motor sürümünü ve arayüz sürümünü (abi) bildirir. Bir ana sürüm içinde işlemler, alanlar ve tanılama kodları kaldırılmaz ve anlamları değişmez; yeni işlemler, alanlar ve kodlar eklenebilir, bu nedenle bilmediklerinizi yok sayın. 2.0 sürümünden itibaren yeni bir ana sürüm altı ay önceden duyurulur.
Motoru kendi modelleriniz üzerinde deneyin.
Değerlendirme 60 gün boyunca ücretsizdir ve tam geliştirici kılavuzunu ve örnekleri içerir.