Holarch Language Engine
Referencia de la API del Language Engine
La interfaz pública del Holarch Language Engine: entra una solicitud JSON y sale una respuesta JSON. Esta página enumera cada operación, sus argumentos y su respuesta, con un pequeño ejemplo. Describe el Holarch Language Engine 2.0.
Ir a: Ejemplo · Puntos de entrada · Solicitudes y respuestas · Diagnósticos · Errores · Registros de elementos · Operaciones · Conjuntos de cambios · Límites
El paquete de evaluación contiene el motor, la biblioteca estándar, la guía completa para desarrolladores con una solicitud y una respuesta reales para cada operación, la lista de códigos de diagnóstico y ejemplos ejecutables. El motor en sí no está en esta página.
Ejemplo: comprobar un modelo mientras se escribe
La integración completa más pequeña: una página con un cuadro de texto y un worker que aloja el motor. Funciona tal cual una vez descomprimido el paquete de evaluación: coloque ambos archivos en examples/00-quick-start/, sirva la carpeta del paquete en la dirección de bucle invertido (loopback) y abra la página.
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 página: index.html
Envía una solicitud analyze por cada cambio. Cada solicitud lleva un número de revisión rev; el motor lo copia en la respuesta, de modo que la página descarta las respuestas a solicitudes que ya ha sustituido.
<!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>
El worker: worker.js
Carga el motor y responde a cada mensaje con una sola llamada. Las direcciones de bucle invertido no necesitan token de licencia.
// 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 solicitud y la respuesta
Para el texto de ejemplo, la página envía:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
El motor responde (tokens y actualizaciones de referencias abreviados):
{
"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": ["…"]
}
rangeestá en unidades de código UTF-16, igual que los índices de las cadenas de JavaScript:text.slice(43, 46)es"Pmp".codees estable entre versiones; el paquete de evaluación tiene mensajes en inglés para cada código (Pmp is not defined here. Check the spelling, or import its package.).tokensson tripletas[kind, from, to]para el resaltado.
Puntos de entrada
En el navegador y en Node.js, el motor es un módulo WebAssembly con un pequeño script de enlace. El script de enlace define un único global, wasm_bindgen: una función de inicialización asíncrona con estas exportaciones.
| Exportación | Firma | Notas |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Instancia el módulo a partir de los bytes .wasm, un WebAssembly.Module, una URL o un Response. Llámela una vez por worker. |
call(request) | string → string | Ejecuta una solicitud JSON y devuelve una respuesta JSON. Nunca lanza una excepción con ninguna cadena de entrada. Un fallo interno lanza un RuntimeError; inicie un nuevo worker después. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Funciona antes de unlock. |
heap_bytes() | () → number | Bytes que ocupan ahora las asignaciones del motor. La memoria de WebAssembly solo crece; compare ambos valores para ver cuánto ahorraría un worker nuevo. Funciona antes de unlock. |
notice() | () → string | El aviso de copyright. Funciona antes de unlock. |
unlock(token) | string → string | Aplica un token de licencia para el origen del worker y responde {ok, …}, o {ok: false, reason}. Los orígenes de bucle invertido no necesitan token. |
La compilación de servidor para Python, disponible con una licencia Enterprise, expone call(request: str) -> str y version() -> str con el mismo JSON.
Solicitudes y respuestas
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opselecciona la operación. Una operación desconocida responde{"error": "unknown-op"}.reves opcional: cualquier número que envíe vuelve sin cambios, también con un error. Úselo para asociar las respuestas con el estado a partir del cual se calcularon.- Las respuestas son objetos JSON. El orden de las claves no tiene significado; ignore las claves que no conozca.
- Un JSON mal formado, una solicitud que no es un objeto o la falta de un argumento obligatorio responden
{"error": "bad-request"}. - El motor nunca lee archivos ni la red. Todo lo que necesita está en la solicitud, en la biblioteca cargada con
library.loado en una sesión de documento.
Desplazamientos
Cada posición (offset, range.from, range.to, y from/to de las ediciones y los mapas de origen) se cuenta en las unidades de quien llama: unidades de código UTF-16 en la compilación WebAssembly, que coinciden con las cadenas de JavaScript y los desplazamientos de los editores, y puntos de código Unicode en la compilación de Python. Los rangos son semiabiertos; un rango con from igual a to marca una posición, como el lugar donde falta un ;.
Diagnósticos
{
"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 | Significado |
|---|---|---|
code | siempre | Código estable, family.rule. El paquete de evaluación enumera cada código con su significado y su corrección. |
severity | siempre, salvo en json_import | "error", "warning" o "info" (una nota sin nada que corregir, como una representación textual en un lenguaje que el motor no comprueba). |
range | operaciones de texto | Dónde está en el texto. Las operaciones de modelo como check no tienen texto ni rango. |
args | siempre | Valores de cadena para el mensaje (name, expected, found, …). Puede estar vacío. |
elementId | diagnósticos semánticos | El elemento cuya comprobación lo generó. |
field | a menudo | El campo del registro afectado (typedBy, value, body.source, …). |
doc | diagnósticos semánticos de analyze | El valor doc de la solicitud, o null. |
Las listas se ordenan por posición. Tras un error de sintaxis, los demás diagnósticos de sintaxis esperan hasta que el analizador vuelve a leer un token correcto, de modo que un error no produce una cascada.
Códigos de error
| Error | Operaciones | Significado |
|---|---|---|
bad-request | todas | JSON mal formado, no es un objeto, o falta un argumento obligatorio o es de un tipo incorrecto. |
unknown-op | todas | No existe esa operación en esta versión. |
limit.input-size | operaciones de texto y de registros | Un texto de más de 8 MiB (UTF-8), o archivos de biblioteca de más de 64 MiB en total. |
limit.nesting | operaciones de registros, json_import, v1_convert | Una cadena de propietarios de un registro (o de un elemento SysML v1) con una profundidad de más de 512. |
limit.elements | v1_convert | Más de 250.000 elementos y entradas de lista en el modelo. |
limit.output-size | v1_convert | El texto convertido superaría los 8 MiB. |
mirror-missing | analyze | mirrorKey designa registros que este worker no tiene; vuelva a enviar records. |
session-missing | check | base no es la sesión de comprobación conservada; vuelva a enviar el modelo completo con una clave nueva. |
not-found | shortest_name | target no está en los registros ni en la biblioteca. |
apply.<reason> | apply | Un cambio no encaja con los registros, como apply.id-used o apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | El desplazamiento no está sobre un nombre, el nombre pertenece a la biblioteca o el nuevo nombre no es válido. |
feature-not-licensed | v1_convert | La operación pertenece a un complemento que la licencia no incluye. Viene con feature y message. |
not-licensed | todas | No hay ninguna licencia aceptada para este origen. Viene con message. |
limit.time, busy | Compilación de Python | Se agotó el presupuesto de tiempo de la llamada, o se ejecutan demasiadas llamadas a la vez. |
Registros de elementos
El texto se convierte en registros de elementos: un objeto JSON que asocia cada id de elemento con un registro plano. Las operaciones de modelo toman y devuelven este 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 | Significado |
|---|---|---|
type | cadena | Metaclase, como Package, PartDefinition, PartUsage, ConnectionUsage o TransitionUsage (los nombres de metaclase de SysML v2). Obligatorio. |
owner | id o null | Elemento propietario; null es el nivel superior. Obligatorio. |
order | cadena | Posición entre los miembros del propietario. Compare como cadenas simples y después por id. Obligatorio. |
role | cadena | Tipo de pertenencia cuando no es un miembro ordinario: subject, actor, require, verify, return, entry, do, exit, then y otros. |
name, shortName | cadena | Tal como se declaró, sin comillas. |
visibility | cadena | public, private o protected cuando se escribe. |
flags | objeto | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel y otros (solo se almacena true); direction: in, out o inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | matriz de referencias | Relaciones. |
multiplicity | {text} | Límites tal como se escribieron ("0..*"). |
value | {text, kind, default?} | kind es "=" o ":="; text es la expresión tal como se escribió. |
body | objeto | Según la metaclase: extremos de conectores, disparadores y efectos de transiciones, destinos y filtros de importaciones, texto de comentarios, expresiones de restricciones, etc. |
doc | cadena | El texto del primer comentario doc. |
xid, mid, docId | cadena | Ids conservados del JSON importado. |
fmt | objeto | Indicaciones para el generador de texto. Consérvelo sin cambios, o elimínelo cuando su cambio haga incorrecta la grafía almacenada. |
Las referencias son {ref, text, chain?, conj?}: ref es el id de destino (null mientras no se resuelve), text el nombre tal como se escribió (un nombre cualificado A::B o una cadena de características a.b.c), chain el id resuelto de cada segmento de la cadena, y conj: true marca un tipo conjugado (~P).
Los ids son UUID en minúsculas. lower los deriva del argumento doc y de la ruta de cada elemento, de modo que el mismo texto y el mismo doc dan los mismos ids. sync y diff conservan los ids existentes y asignan a los elementos nuevos ids a partir de su seed. Los elementos de la biblioteca tienen los mismos ids en todas las versiones (lib_id).
Operaciones
Los argumentos entre corchetes son opcionales. Toda solicitud puede llevar rev.
| Operación | Argumentos | Respuesta |
|---|---|---|
version | — | {core, abi, records, checkParts}: records es la revisión del formato de registros; checkParts indica que check admite el modelo de una sesión por partes. |
library.load | files: [{path, text}], los archivos de biblioteca .sysml y .kerml en cualquier orden (64 MiB como máximo) | {files, elements, skipped, packages}. Sustituye la biblioteca y borra todas las sesiones de documento. |
library.status | — | {files, elements} de la biblioteca cargada. |
lib_id | qname, como ISQ::MassValue | {id}, el id del elemento de la biblioteca para ese nombre. |
lex | text | {tokens, diagnostics}: tokens [kind, from, to] y diagnósticos léxicos. Rápido; para un primer pintado. |
roundtrip | text | {text, same, diagnostics}: el texto reconstruido a partir de sus tokens; una autoprueba del analizador léxico. |
parse | text | {errors, diagnostics}: solo sintaxis, sin resolución de nombres. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. La operación principal del editor: tokens con tipos semánticos (def, ref, unresolved), diagnósticos sintácticos y semánticos, y actualizaciones de referencias. Con una clave doc, el motor conserva una sesión y vuelve a comprobar solo lo que puede alcanzar una edición; records resuelve los nombres frente al resto del modelo. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: registros de elementos con referencias sin resolver, los ids de nivel superior en el orden del texto y los miembros omitidos por errores de sintaxis. |
check | records; [session], o [session], base, changes; [load] | {refs, diagnostics}: el destino resuelto de cada referencia cuyo ref almacenado difiere, y diagnósticos con elementId y field. Con una clave session, el motor conserva el modelo; una solicitud posterior lo indica como base con solo los changes ({id: record or null}), y el motor vuelve a comprobar solo los paquetes que pueden alcanzar los cambios, con la misma respuesta que una comprobación completa. load: "part" envía un modelo grande en varias solicitudes y load: "end" lo comprueba, de modo que el modelo completo nunca tiene que estar en memoria como una sola solicitud. {"op": "check.drop"} libera el modelo conservado. |
evaluate | records; [ids] | {values}: por id de elemento, un valor {kind, text, …}, donde kind es number, quantity (con unit y dimension), boolean, string, unit, sequence, element o unknown. Muestre text. |
analyze_case | records; [ids] | {cases, requirements}: cada satisfy con su estado (satisfied, violated, not-applicable, unknown) y los valores de sus restricciones, y cada caso de análisis y de verificación con su resultado. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …}, o {elementId: null} fuera de un nombre. |
definition | como hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | como hover | {from, to, items}: sustituya from..to por el insert o la label de un elemento. |
rename | como hover, más name | {elementId, changes}: [{from, to, insert}] para cada aparición en el texto. |
shortest_name | records, target; [context] | {text}: el nombre más corto que se resuelve a target desde context. |
print_records | records; [roots], [dialect] | {text}. Los elementos sin cambios se imprimen byte a byte. |
canon_lines | records o text; [roots], [dialect], [per], [ids] | {lines, bytes}: el tamaño del modelo en líneas canónicas, las líneas del texto que el motor imprime para él sin documentación, comentarios ni líneas en blanco, de modo que el recuento no depende de cómo se escribió el texto. Con per, la parte de cada elemento; con ids, solo las partes de esos elementos, para mantener un recuento actualizado tras un cambio. |
print | records; [root], [text] | {text, map, edits?}: el texto, un mapa de origen [{id, from, to}] y las ediciones que convierten el texto dado en el nuevo. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: el conjunto de cambios que hace que los registros coincidan con el texto, conservando los ids existentes. Con apply: true, en su lugar los registros con el conjunto de cambios aplicado ({count, diagnostics, notApplied, roots, records}), lo que necesita menos memoria para un texto grande. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: un borrador de texto fusionado con los cambios del modelo hechos mientras tanto. |
diff | old, new; [base], [seed] | {changes, ids}: el conjunto de cambios de old a new, y el id que tiene cada elemento de new en el resultado. |
apply | records, changes | {records} con los cambios aplicados, o {error: "apply.<reason>"}. |
edits | old, new (cadenas) | {edits}: sustituciones mínimas que tienen en cuenta las líneas. |
json_export | records; [ext] | {elements}: elementos SysML v2 JSON (@id, @type), incluidos los elementos de relación. Con ext (el valor predeterminado), cada elemento lleva lo que json_import necesita para restaurar los registros con exactitud. |
json_import | elements: una matriz, {elements: […]}, o versiones de datos de la API | {records, diagnostics}. Los ids que no son UUID reciben UUID, y el original se conserva en xid. Los elementos de tipos que el motor no interpreta se conservan como registros opacos que json_export vuelve a escribir sin cambios, con una nota json.kept-unsupported por tipo. |
v1_convert | model: un modelo SysML v1 leído desde XMI por su integración; [check], [items] | {text, report, diagnostics?, library?}: texto SysML v2 y un informe de lo que se convirtió, se aproximó o se descartó. Forma parte del complemento de migración, con licencia aparte. |
Conjuntos de cambios
sync y diff devuelven, y apply recibe, una matriz ordenada de cambios. Las creaciones y los desplazamientos van en el orden del documento, los propietarios antes que los miembros; las eliminaciones van al final.
| Cambio | Significado |
|---|---|
{op: "create", id, fields, after?, before?} | Un elemento nuevo, colocado después o antes de un hermano, o al final. |
{op: "update", id, patch} | Cambios de campos; null elimina un campo. Nunca cambia owner ni order. |
{op: "move", id, owner, after?, before?} | Un nuevo propietario o una nueva posición. |
{op: "remove", ids} | Elimina los elementos y todo lo que contienen. |
Límites
Por encima de un límite, el motor responde con un diagnóstico o un código de error, nunca con un bloqueo ni un fallo. Cada operación tarda un tiempo proporcional a su entrada.
| Límite | Valor | Por encima del límite |
|---|---|---|
| Tamaño del texto | 8 MiB (UTF-8) | limit.input-size |
| Longitud de línea | 64 KiB (UTF-8) | limit.line-length por cada línea larga |
| Anidamiento de cuerpos | 256 niveles | limit.nesting; la parte más profunda se omite |
| Anidamiento de expresiones | 512 niveles | limit.expression-depth |
| Cadena de propietarios de un registro | 512 niveles | {error: "limit.nesting"} |
| Archivos de biblioteca, en total | 64 MiB | {error: "limit.input-size"} |
| Importación JSON | 500.000 elementos | json.too-many-elements; el resto no se lee |
Modelo SysML v1 (v1_convert) | 250.000 elementos y entradas de lista; cadenas de propietarios de 512 niveles; texto de 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Nuevo nombre en rename | De 1 a 1000 caracteres, sin caracteres de control | {error: "rename.invalid-name"} |
La compilación para navegador no tiene límite de tiempo propio: ejecútela en un worker y termine el worker cuando no responda a tiempo. Las respuestas contienen texto de la entrada, como nombres y documentación; escápelo como cualquier entrada de usuario antes de insertarlo en una página.
Versiones y estabilidad
version() indica la versión del motor y la versión de la interfaz (abi). Dentro de una versión mayor, las operaciones, los campos y los códigos de diagnóstico no se eliminan ni cambian de significado; pueden añadirse nuevas operaciones, campos y códigos, así que ignore lo que no conozca. A partir de la versión 2.0, una nueva versión mayor se anuncia con seis meses de antelación.
Pruebe el motor con sus propios modelos.
La evaluación es gratuita durante 60 días e incluye la guía completa para desarrolladores y los ejemplos.