Holarch Language Engine
Riferimento API del Language Engine
L’interfaccia pubblica dell’Holarch Language Engine: una richiesta JSON in ingresso, una risposta JSON in uscita. Questa pagina elenca ogni operazione, i suoi argomenti e la sua risposta, con un piccolo esempio. Descrive l’Holarch Language Engine 2.0.
Vai a: Esempio · Punti di ingresso · Richieste e risposte · Diagnostica · Errori · Record degli elementi · Operazioni · Insiemi di modifiche · Limiti
Il pacchetto di valutazione contiene il motore, la libreria standard, la guida completa per sviluppatori con una richiesta e una risposta reali per ogni operazione, l’elenco dei codici di diagnostica ed esempi eseguibili. Il motore stesso non si trova in questa pagina.
Esempio: controllare un modello durante la digitazione
L’integrazione completa più piccola: una pagina con una casella di testo e un worker che ospita il motore. Funziona così com’è una volta decompresso il pacchetto di valutazione: mettere entrambi i file in examples/00-quick-start/, servire la cartella del pacchetto sull’indirizzo di loopback e aprire la pagina.
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/
La pagina: index.html
Invia una richiesta analyze per ogni modifica. Ogni richiesta porta un numero di revisione rev; il motore lo copia nella risposta, così la pagina scarta le risposte a richieste che ha già sostituito.
<!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>
Il worker: worker.js
Carica il motore e risponde a ogni messaggio con una sola chiamata. Gli indirizzi di loopback non richiedono un token di licenza.
// 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
}
};
La richiesta e la risposta
Per il testo di esempio, la pagina invia:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
Il motore risponde (token e aggiornamenti dei riferimenti abbreviati):
{
"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è in unità di codice UTF-16, come gli indici delle stringhe JavaScript:text.slice(43, 46)è"Pmp".codeè stabile tra le versioni; il pacchetto di valutazione contiene messaggi in inglese per ogni codice (Pmp is not defined here. Check the spelling, or import its package.).tokenssono triple[kind, from, to]per l’evidenziazione.
Punti di ingresso
Nel browser e in Node.js, il motore è un modulo WebAssembly con un piccolo script di collegamento. Lo script definisce un’unica variabile globale, wasm_bindgen: una funzione di inizializzazione asincrona con queste esportazioni.
| Esportazione | Firma | Note |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Istanzia il modulo dai byte .wasm, da un WebAssembly.Module, da un URL o da una Response. Chiamare una volta per worker. |
call(request) | string → string | Esegue una richiesta JSON e restituisce una risposta JSON. Non genera mai eccezioni per qualsiasi stringa di input. Un errore interno genera un RuntimeError; dopo di esso avviare un nuovo worker. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Funziona prima di unlock. |
heap_bytes() | () → number | Byte occupati ora dalle allocazioni del motore. La memoria WebAssembly cresce soltanto; confrontare i due valori per vedere quanto risparmierebbe un worker nuovo. Funziona prima di unlock. |
notice() | () → string | L’avviso di copyright. Funziona prima di unlock. |
unlock(token) | string → string | Applica un token di licenza per l’origine del worker e risponde {ok, …}, oppure {ok: false, reason}. Le origini di loopback non richiedono un token. |
La build server per Python, disponibile con una licenza Enterprise, espone call(request: str) -> str e version() -> str con lo stesso JSON.
Richieste e risposte
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opseleziona l’operazione. Un’operazione sconosciuta risponde{"error": "unknown-op"}.revè facoltativo: qualsiasi numero inviato torna invariato, anche con un errore. Usarlo per associare le risposte allo stato da cui sono state calcolate.- Le risposte sono oggetti JSON. L’ordine delle chiavi non ha significato; ignorare le chiavi sconosciute.
- JSON malformato, una richiesta che non è un oggetto o un argomento obbligatorio mancante rispondono
{"error": "bad-request"}. - Il motore non legge mai file né la rete. Tutto ciò di cui ha bisogno si trova nella richiesta, nella libreria caricata con
library.loado in una sessione di documento.
Offset
Ogni posizione (offset, range.from, range.to, e from/to di modifiche e source map) è espressa nelle unità del chiamante: unità di codice UTF-16 nella build WebAssembly, in linea con le stringhe JavaScript e gli offset degli editor, e code point Unicode nella build Python. Gli intervalli sono semiaperti; un intervallo con from uguale a to indica una posizione, ad esempio dove manca un ;.
Diagnostica
{
"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"
}
| Campo | Presente | Significato |
|---|---|---|
code | sempre | Codice stabile, family.rule. Il pacchetto di valutazione elenca ogni codice con il suo significato e la correzione. |
severity | sempre, tranne in json_import | "error", "warning" o "info" (una nota senza nulla da correggere, come una rappresentazione testuale in un linguaggio che il motore non controlla). |
range | operazioni sul testo | Dove nel testo. Le operazioni sul modello come check non hanno testo né intervallo. |
args | sempre | Valori stringa per il messaggio (name, expected, found, …). Può essere vuoto. |
elementId | diagnostica semantica | L’elemento il cui controllo l’ha generata. |
field | spesso | Il campo del record interessato (typedBy, value, body.source, …). |
doc | diagnostica semantica di analyze | Il valore doc della richiesta, oppure null. |
Gli elenchi sono ordinati per posizione. Dopo un errore di sintassi, le ulteriori diagnostiche di sintassi attendono che il parser legga di nuovo un token valido, così un errore non produce una cascata.
Codici di errore
| Errore | Operazioni | Significato |
|---|---|---|
bad-request | tutte | JSON malformato, non un oggetto, oppure un argomento obbligatorio mancante o di tipo errato. |
unknown-op | tutte | Nessuna operazione con questo nome in questa versione. |
limit.input-size | operazioni su testo e record | Un testo oltre 8 MiB (UTF-8), oppure file di libreria oltre 64 MiB in totale. |
limit.nesting | operazioni sui record, json_import, v1_convert | Una catena di proprietari di un record (o di un elemento SysML v1) più profonda di 512. |
limit.elements | v1_convert | Più di 250.000 elementi e voci di elenco nel modello. |
limit.output-size | v1_convert | Il testo convertito supererebbe 8 MiB. |
mirror-missing | analyze | mirrorKey indica record che questo worker non contiene; inviare di nuovo records. |
session-missing | check | base non è la sessione di controllo conservata; inviare di nuovo l’intero modello con una nuova chiave. |
not-found | shortest_name | target non è nei record né nella libreria. |
apply.<reason> | apply | Una modifica non è compatibile con i record, come apply.id-used o apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | L’offset non è su un nome, il nome appartiene alla libreria, oppure il nuovo nome non è valido. |
feature-not-licensed | v1_convert | L’operazione appartiene a un componente aggiuntivo non incluso nella licenza. Viene fornito con feature e message. |
not-licensed | tutte | Nessuna licenza accettata per questa origine. Viene fornito con message. |
limit.time, busy | Build Python | Il tempo a disposizione della chiamata è scaduto, oppure ci sono troppe chiamate in esecuzione contemporaneamente. |
Record degli elementi
Il testo diventa record degli elementi: un oggetto JSON che associa ogni id di elemento a un record piatto. Le operazioni sul modello accettano e restituiscono questo formato.
{
"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" }
}
| Campo | Forma | Significato |
|---|---|---|
type | stringa | Metaclasse, come Package, PartDefinition, PartUsage, ConnectionUsage o TransitionUsage (i nomi delle metaclassi SysML v2). Obbligatorio. |
owner | id o null | Elemento proprietario; null indica il livello superiore. Obbligatorio. |
order | stringa | Posizione tra i membri del proprietario. Confrontare come semplici stringhe, poi per id. Obbligatorio. |
role | stringa | Tipo di appartenenza quando non è un membro ordinario: subject, actor, require, verify, return, entry, do, exit, then e altri. |
name, shortName | stringa | Come dichiarato, senza virgolette. |
visibility | stringa | public, private o protected quando scritto. |
flags | oggetto | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel e altri (viene memorizzato solo true); direction: in, out o inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | array di riferimenti | Relazioni. |
multiplicity | {text} | Limiti come scritti ("0..*"). |
value | {text, kind, default?} | kind è "=" o ":="; text è l’espressione come scritta. |
body | oggetto | Per metaclasse: estremi dei connettori, trigger ed effetti delle transizioni, destinazioni e filtri degli import, testo dei commenti, espressioni dei vincoli e così via. |
doc | stringa | Il testo del primo commento doc. |
xid, mid, docId | stringa | Id conservati dal JSON importato. |
fmt | oggetto | Suggerimenti per la stampa. Lasciarlo invariato, oppure eliminarlo quando la modifica rende errata la grafia memorizzata. |
I riferimenti sono {ref, text, chain?, conj?}: ref è l’id di destinazione (null finché non è risolto), text il nome come scritto (un nome qualificato A::B o una catena di feature a.b.c), chain l’id risolto di ogni segmento della catena, e conj: true contrassegna un tipo coniugato (~P).
Gli id sono UUID in minuscolo. lower li ricava dall’argomento doc e dal percorso di ogni elemento, quindi lo stesso testo e lo stesso doc danno gli stessi id. sync e diff mantengono gli id esistenti e assegnano ai nuovi elementi id derivati dal proprio seed. Gli elementi della libreria hanno gli stessi id in ogni versione (lib_id).
Operazioni
Gli argomenti tra parentesi quadre sono facoltativi. Ogni richiesta può portare rev.
| Operazione | Argomenti | Risposta |
|---|---|---|
version | — | {core, abi, records, checkParts}: records è la revisione del formato dei record; checkParts indica che check accetta il modello di una sessione in parti. |
library.load | files: [{path, text}], i file di libreria .sysml e .kerml in qualsiasi ordine (al massimo 64 MiB) | {files, elements, skipped, packages}. Sostituisce la libreria e cancella ogni sessione di documento. |
library.status | — | {files, elements} della libreria caricata. |
lib_id | qname, come ISQ::MassValue | {id}, l’id dell’elemento di libreria per quel nome. |
lex | text | {tokens, diagnostics}: token [kind, from, to] e diagnostica lessicale. Veloce; per una prima visualizzazione. |
roundtrip | text | {text, same, diagnostics}: il testo ricostruito dai suoi token; un autotest del lexer. |
parse | text | {errors, diagnostics}: solo sintassi, nessuna risoluzione dei nomi. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. L’operazione principale dell’editor: token con tipi semantici (def, ref, unresolved), diagnostica sintattica e semantica, e aggiornamenti dei riferimenti. Con una chiave doc il motore mantiene una sessione e ricontrolla solo ciò che una modifica può raggiungere; records risolve i nomi rispetto al resto del modello. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: record degli elementi con riferimenti non risolti, gli id di livello superiore nell’ordine del testo, e i membri saltati a causa di errori di sintassi. |
check | records; [session], oppure [session], base, changes; [load] | {refs, diagnostics}: la destinazione risolta di ogni riferimento il cui ref memorizzato è diverso, e diagnostica con elementId e field. Con una chiave session il motore conserva il modello; una richiesta successiva lo indica come base con le sole changes ({id: record or null}) e il motore ricontrolla solo i package che le modifiche possono raggiungere, con la stessa risposta di un controllo completo. load: "part" invia un modello grande in più richieste e load: "end" lo controlla, così l’intero modello non deve mai essere in memoria come un’unica richiesta. {"op": "check.drop"} libera il modello conservato. |
evaluate | records; [ids] | {values}: per ogni id di elemento un valore {kind, text, …}, dove kind è number, quantity (con unit e dimension), boolean, string, unit, sequence, element o unknown. Mostrare text. |
analyze_case | records; [ids] | {cases, requirements}: ogni satisfy con il suo stato (satisfied, violated, not-applicable, unknown) e i valori dei vincoli, e ogni analysis case e verification case con il suo risultato. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …}, oppure {elementId: null} fuori da un nome. |
definition | come hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | come hover | {from, to, items}: sostituire from..to con insert o label di un elemento. |
rename | come hover, più name | {elementId, changes}: [{from, to, insert}] per ogni occorrenza nel testo. |
shortest_name | records, target; [context] | {text}: il nome più breve che si risolve in target a partire da context. |
print_records | records; [roots], [dialect] | {text}. Gli elementi invariati vengono stampati byte per byte. |
canon_lines | records o text; [roots], [dialect], [per], [ids] | {lines, bytes}: la dimensione del modello in righe canoniche, cioè le righe del testo che il motore stampa per esso senza documentazione, commenti o righe vuote, così il conteggio non dipende da come è stato scritto il testo. Con per, la quota di ogni elemento; con ids, solo le quote di quegli elementi, per mantenere aggiornato un conteggio dopo una modifica. |
print | records; [root], [text] | {text, map, edits?}: il testo, una source map [{id, from, to}] e le modifiche che trasformano il testo dato in quello nuovo. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: l’insieme di modifiche che allinea i record al testo, mantenendo gli id esistenti. Con apply: true, invece, i record con l’insieme di modifiche applicato ({count, diagnostics, notApplied, roots, records}), il che richiede meno memoria per un testo grande. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: una bozza di testo unita con le modifiche al modello apportate nel frattempo. |
diff | old, new; [base], [seed] | {changes, ids}: l’insieme di modifiche da old a new, e l’id che ogni elemento di new ha nel risultato. |
apply | records, changes | {records} con le modifiche applicate, oppure {error: "apply.<reason>"}. |
edits | old, new (stringhe) | {edits}: sostituzioni minime che tengono conto delle righe. |
json_export | records; [ext] | {elements}: elementi SysML v2 JSON (@id, @type), compresi gli elementi di relazione. Con ext (il valore predefinito) ogni elemento contiene ciò di cui json_import ha bisogno per ripristinare esattamente i record. |
json_import | elements: un array, {elements: […]}, o versioni dei dati dell’API | {records, diagnostics}. Gli id che non sono UUID ricevono UUID, con l’originale conservato in xid. Gli elementi di tipi che il motore non interpreta vengono conservati come record opachi che json_export riscrive invariati, con una nota json.kept-unsupported per tipo. |
v1_convert | model: un modello SysML v1 letto da XMI dalla propria integrazione; [check], [items] | {text, report, diagnostics?, library?}: testo SysML v2 e un rapporto su che cosa è stato convertito, approssimato o eliminato. Fa parte del componente aggiuntivo di migrazione, concesso in licenza separatamente. |
Insiemi di modifiche
sync e diff restituiscono, e apply accetta, un array ordinato di modifiche. Creazioni e spostamenti seguono l’ordine del documento, i proprietari prima dei membri; le rimozioni vengono per ultime.
| Modifica | Significato |
|---|---|
{op: "create", id, fields, after?, before?} | Un nuovo elemento, posizionato dopo o prima di un elemento fratello, oppure per ultimo. |
{op: "update", id, patch} | Modifiche di campi; null elimina un campo. Non modifica mai owner o order. |
{op: "move", id, owner, after?, before?} | Un nuovo proprietario o una nuova posizione. |
{op: "remove", ids} | Rimuove gli elementi e tutto ciò che possiedono. |
Limiti
Oltre un limite il motore risponde con una diagnostica o un codice di errore, mai con un blocco o un crash. Ogni operazione richiede un tempo proporzionale al suo input.
| Limite | Valore | Oltre il limite |
|---|---|---|
| Dimensione del testo | 8 MiB (UTF-8) | limit.input-size |
| Lunghezza della riga | 64 KiB (UTF-8) | limit.line-length per ogni riga lunga |
| Annidamento dei corpi | 256 livelli | limit.nesting; la parte più profonda viene saltata |
| Annidamento delle espressioni | 512 livelli | limit.expression-depth |
| Catena dei proprietari dei record | 512 livelli | {error: "limit.nesting"} |
| File di libreria, totale | 64 MiB | {error: "limit.input-size"} |
| Importazione JSON | 500.000 elementi | json.too-many-elements; il resto non viene letto |
Modello SysML v1 (v1_convert) | 250.000 elementi e voci di elenco; catene di proprietari di 512 livelli; testo di 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Nuovo nome in rename | Da 1 a 1.000 caratteri, senza caratteri di controllo | {error: "rename.invalid-name"} |
La build per browser non ha un proprio limite di tempo: eseguirla in un worker e terminare il worker quando non risponde in tempo. Le risposte contengono testo proveniente dall’input, come nomi e documentazione; eseguirne l’escape come per qualsiasi input dell’utente prima di inserirlo in una pagina.
Versioni e stabilità
version() riporta la versione del motore e la versione dell’interfaccia (abi). All’interno di una versione principale, operazioni, campi e codici di diagnostica non vengono rimossi né cambiano significato; possono essere aggiunti nuove operazioni, campi e codici, quindi ignorare ciò che non si conosce. Dalla versione 2.0 in poi, una nuova versione principale viene annunciata con sei mesi di anticipo.
Provare il motore sui propri modelli.
La valutazione è gratuita per 60 giorni e include la guida completa per sviluppatori e gli esempi.