Holarch Language Engine
Referência da API do Language Engine
A interface pública do Holarch Language Engine: uma requisição JSON entra, uma resposta JSON sai. Esta página lista cada operação, seus argumentos e sua resposta, com um pequeno exemplo. Ela descreve o Holarch Language Engine 2.0.
Ir para: Exemplo · Pontos de entrada · Requisições e respostas · Diagnósticos · Erros · Registros de elementos · Operações · Conjuntos de mudanças · Limites
O pacote de avaliação contém o engine, a biblioteca padrão, o guia completo do desenvolvedor com uma requisição e uma resposta reais para cada operação, a lista de códigos de diagnóstico e exemplos executáveis. O engine em si não está nesta página.
Exemplo: checar um modelo enquanto você digita
A menor integração completa: uma página com uma caixa de texto e um worker que hospeda o engine. Ela roda como está depois que o pacote de avaliação é descompactado: coloque os dois arquivos em examples/00-quick-start/, sirva a pasta do pacote no endereço de loopback e abra a 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/
A página: index.html
Ela envia uma requisição analyze por mudança. Cada requisição traz um número de revisão rev; o engine o copia na resposta, então a página descarta respostas a requisições que ela já substituiu.
<!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>
O worker: worker.js
Ele carrega o engine e responde a cada mensagem com uma única chamada. Endereços de loopback não precisam de token de licença.
// 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
}
};
A requisição e a resposta
Para o texto de exemplo, a página envia:
{ "op": "analyze", "doc": "demo", "rev": 1,
"text": "package Demo {\n part def Pump;\n part p : Pmp;\n}" }
O engine responde (tokens e atualizações de referências 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": ["…"]
}
rangeé em unidades de código UTF-16, as mesmas dos índices de string do JavaScript:text.slice(43, 46)é"Pmp".codeé estável entre versões; o pacote de avaliação tem mensagens em inglês para cada código (Pmp is not defined here. Check the spelling, or import its package.).tokenssão triplas[kind, from, to]para o realce de sintaxe.
Pontos de entrada
No navegador e no Node.js, o engine é um módulo WebAssembly com um pequeno script de ligação. Esse script define um único global, wasm_bindgen: uma função de inicialização assíncrona com estas exportações.
| Exportar | Assinatura | Observações |
|---|---|---|
wasm_bindgen(init) | ({module_or_path}) → Promise | Instancia o módulo a partir dos bytes do .wasm, de um WebAssembly.Module, de uma URL ou de um Response. Chame uma vez por worker. |
call(request) | string → string | Executa uma requisição JSON e retorna uma resposta JSON. Nunca lança exceção para nenhuma string de entrada. Uma falha interna lança um RuntimeError; depois disso, inicie um novo worker. |
version() | () → string | {"core": "2.0.0", "abi": 1, "records": 2, "checkParts": true}. Funciona antes de unlock. |
heap_bytes() | () → number | Bytes que as alocações do engine ocupam agora. A memória WebAssembly só cresce; compare os dois para ver quanto um worker novo economizaria. Funciona antes de unlock. |
notice() | () → string | O aviso de copyright. Funciona antes de unlock. |
unlock(token) | string → string | Aplica um token de licença para a origem do worker e responde {ok, …}, ou {ok: false, reason}. Origens de loopback não precisam de token. |
O build de servidor para Python, disponível com uma licença Enterprise, expõe call(request: str) -> str e version() -> str com o mesmo JSON.
Requisições e respostas
request: {"op": "<name>", "rev"?: number, …arguments}
answer: {"rev"?: number, …result}
or {"rev"?: number, "error": "<code>", "message"?: string}
opseleciona a operação. Uma op desconhecida responde{"error": "unknown-op"}.revé opcional: qualquer número que você enviar volta inalterado, também com um erro. Use-o para associar as respostas ao estado a partir do qual foram calculadas.- As respostas são objetos JSON. A ordem das chaves não tem significado; ignore as chaves que você não conhece.
- JSON malformado, uma requisição que não é um objeto ou um argumento obrigatório ausente responde
{"error": "bad-request"}. - O engine nunca lê arquivos nem a rede. Tudo o de que ele precisa está na requisição, na biblioteca carregada com
library.loadou em uma sessão de documento.
Offsets
Cada posição (offset, range.from, range.to e from/to de edições e mapas de origem) é contada nas unidades do chamador: unidades de código UTF-16 no build WebAssembly, correspondendo às strings do JavaScript e aos offsets de editores, e code points Unicode no build Python. Os intervalos são semiabertos; um intervalo com from igual a to marca uma posição, como onde falta um ;.
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 | sempre | Código estável, family.rule. O pacote de avaliação lista cada código com seu significado e correção. |
severity | sempre, exceto em json_import | "error", "warning" ou "info" (uma nota sem nada a corrigir, como uma representação textual em uma linguagem que o engine não checa). |
range | operações de texto | Onde no texto. Operações de modelo como check não têm texto nem intervalo. |
args | sempre | Valores de string para a mensagem (name, expected, found, …). Pode estar vazio. |
elementId | diagnósticos semânticos | O elemento cuja checagem o gerou. |
field | frequentemente | O campo do registro em questão (typedBy, value, body.source, …). |
doc | diagnósticos semânticos de analyze | O valor doc da requisição, ou null. |
As listas são ordenadas por posição. Após um erro de sintaxe, os diagnósticos de sintaxe seguintes aguardam até que o parser leia de novo um token válido, para que um único erro não produza uma cascata.
Códigos de erro
| Erro | Operações | Significado |
|---|---|---|
bad-request | todas | JSON malformado, não é um objeto, ou um argumento obrigatório ausente ou de tipo errado. |
unknown-op | todas | Não existe essa operação nesta versão. |
limit.input-size | operações de texto e de registros | Um texto acima de 8 MiB (UTF-8), ou arquivos de biblioteca acima de 64 MiB no total. |
limit.nesting | operações de registros, json_import, v1_convert | Uma cadeia de proprietários de um registro (ou elemento SysML v1) com mais de 512 níveis. |
limit.elements | v1_convert | Mais de 250.000 elementos e entradas de lista no modelo. |
limit.output-size | v1_convert | O texto convertido ultrapassaria 8 MiB. |
mirror-missing | analyze | mirrorKey se refere a registros que este worker não possui; envie records de novo. |
session-missing | check | base não é a sessão de checagem mantida; envie o modelo inteiro de novo com uma nova chave. |
not-found | shortest_name | target não está nos registros nem na biblioteca. |
apply.<reason> | apply | Uma mudança não se encaixa nos registros, como apply.id-used ou apply.create. |
rename.not-a-name, rename.library, rename.invalid-name | rename | O offset não está sobre um nome, o nome pertence à biblioteca ou o novo nome não é válido. |
feature-not-licensed | v1_convert | A operação pertence a um complemento que a licença não inclui. Vem com feature e message. |
not-licensed | todas | Nenhuma licença aceita para esta origem. Vem com message. |
limit.time, busy | build Python | O orçamento de tempo da chamada se esgotou, ou há chamadas demais em execução ao mesmo tempo. |
Registros de elementos
O texto se torna registros de elementos: um objeto JSON que mapeia cada id de elemento para um registro plano. As operações de modelo recebem e retornam esse 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 | string | Metaclasse, como Package, PartDefinition, PartUsage, ConnectionUsage ou TransitionUsage (os nomes de metaclasses do SysML v2). Obrigatório. |
owner | id ou null | Elemento proprietário; null é o nível superior. Obrigatório. |
order | string | Posição entre os membros do proprietário. Compare como strings simples e, depois, por id. Obrigatório. |
role | string | Tipo de associação quando não é um membro comum: subject, actor, require, verify, return, entry, do, exit, then e outros. |
name, shortName | string | Como declarado, sem aspas. |
visibility | string | public, private ou protected quando escrito. |
flags | objeto | abstract, variation, ref, readonly, derived, end, ordered, nonunique, parallel e outros (só true é armazenado); direction: in, out ou inout. |
typedBy, specializes, subsets, redefines, references, conjugates, disjoins | array de referências | Relacionamentos. |
multiplicity | {text} | Limites como escritos ("0..*"). |
value | {text, kind, default?} | kind é "=" ou ":="; text é a expressão como escrita. |
body | objeto | Por metaclasse: extremidades de conectores, gatilhos e efeitos de transições, alvos e filtros de imports, texto de comentários, expressões de restrições e assim por diante. |
doc | string | O texto do primeiro comentário doc. |
xid, mid, docId | string | Ids mantidos do JSON importado. |
fmt | objeto | Dicas para o printer. Mantenha inalterado, ou exclua quando sua mudança tornar a grafia armazenada incorreta. |
Referências são {ref, text, chain?, conj?}: ref é o id do alvo (null enquanto não resolvido), text o nome como escrito (um nome qualificado A::B ou uma cadeia de features a.b.c), chain o id resolvido de cada segmento da cadeia, e conj: true marca um tipo conjugado (~P).
Ids são UUIDs em minúsculas. lower os deriva do argumento doc e do caminho de cada elemento, então o mesmo texto e o mesmo doc dão os mesmos ids. sync e diff mantêm os ids existentes e dão aos novos elementos ids a partir do seu seed. Os elementos da biblioteca têm os mesmos ids em todas as versões (lib_id).
Operações
Os argumentos entre colchetes são opcionais. Toda requisição pode trazer rev.
| Operação | Argumentos | Resposta |
|---|---|---|
version | — | {core, abi, records, checkParts}: records é a revisão do formato de registros; checkParts indica que check aceita o modelo de uma sessão em partes. |
library.load | files: [{path, text}], os arquivos de biblioteca .sysml e .kerml em qualquer ordem (no máximo 64 MiB) | {files, elements, skipped, packages}. Substitui a biblioteca e limpa todas as sessões de documento. |
library.status | — | {files, elements} da biblioteca carregada. |
lib_id | qname, como ISQ::MassValue | {id}, o id do elemento de biblioteca para esse nome. |
lex | text | {tokens, diagnostics}: tokens [kind, from, to] e diagnósticos léxicos. Rápido; para uma primeira renderização. |
roundtrip | text | {text, same, diagnostics}: o texto reconstruído a partir de seus tokens; um autoteste do lexer. |
parse | text | {errors, diagnostics}: somente sintaxe, sem resolução de nomes. |
analyze | text; [doc], [session], [root], [records], [mirrorKey], [tokensBase], [refs] | {tokens or tokenDelta, diagnostics, refs}. A principal operação do editor: tokens com tipos semânticos (def, ref, unresolved), diagnósticos de sintaxe e semânticos, e atualizações de referências. Com uma chave doc, o engine mantém uma sessão e checa de novo só o que uma edição pode alcançar; records resolvem nomes em relação ao resto do modelo. |
lower | text; [doc] | {records, roots, skipped, diagnostics}: registros de elementos com referências não resolvidas, os ids de nível superior na ordem do texto e os membros ignorados por causa de erros de sintaxe. |
check | records; [session], ou [session], base, changes; [load] | {refs, diagnostics}: o alvo resolvido de cada referência cujo ref armazenado difere, e diagnósticos com elementId e field. Com uma chave session, o engine mantém o modelo; uma requisição posterior o indica como base com apenas as changes ({id: record or null}) e o engine checa de novo só os pacotes que as mudanças podem alcançar, com a mesma resposta de uma checagem completa. load: "part" envia um modelo grande em várias requisições e load: "end" o checa, de modo que o modelo inteiro nunca precisa estar na memória como uma única requisição. {"op": "check.drop"} libera o modelo mantido. |
evaluate | records; [ids] | {values}: por id de elemento, um valor {kind, text, …}, em que kind é number, quantity (com unit e dimension), boolean, string, unit, sequence, element ou unknown. Mostre text. |
analyze_case | records; [ids] | {cases, requirements}: cada satisfy com seu status (satisfied, violated, not-applicable, unknown) e valores de restrição, e cada caso de análise e de verificação com seu resultado. |
hover | text, offset; [doc], [root], [records] | {elementId, type, name, qualifiedName, range, doc?, value?, …}, ou {elementId: null} fora de um nome. |
definition | como hover | {elementId, qualifiedName, range?, doc?, library?}. |
complete | como hover | {from, to, items}: substitua from..to pelo insert ou label de um item. |
rename | como hover, mais name | {elementId, changes}: [{from, to, insert}] para cada ocorrência no texto. |
shortest_name | records, target; [context] | {text}: o nome mais curto que resolve para target a partir de context. |
print_records | records; [roots], [dialect] | {text}. Elementos inalterados são impressos byte a byte. |
canon_lines | records ou text; [roots], [dialect], [per], [ids] | {lines, bytes}: o tamanho do modelo em linhas canônicas, as linhas do texto que o engine imprime para ele sem documentação, comentários ou linhas em branco, de modo que a contagem não depende de como o texto foi escrito. Com per, a parcela de cada elemento; com ids, apenas as parcelas desses elementos, para manter uma contagem atualizada após uma mudança. |
print | records; [root], [text] | {text, map, edits?}: o texto, um mapa de origem [{id, from, to}] e as edições que transformam o texto dado no novo. |
sync | text, records; [root], [seed], [apply] | {changes, notApplied, diagnostics}: o conjunto de mudanças que faz os registros corresponderem ao texto, mantendo os ids existentes. Com apply: true, em vez disso, os registros com o conjunto de mudanças aplicado ({count, diagnostics, notApplied, roots, records}), o que exige menos memória para um texto grande. |
rebase | base, text, records; [root] | {text, clean, conflicts, theirs}: um rascunho de texto mesclado com as mudanças no modelo feitas nesse meio-tempo. |
diff | old, new; [base], [seed] | {changes, ids}: o conjunto de mudanças de old para new, e o id que cada elemento de new tem no resultado. |
apply | records, changes | {records} com as mudanças aplicadas, ou {error: "apply.<reason>"}. |
edits | old, new (strings) | {edits}: substituições mínimas, cientes das linhas. |
json_export | records; [ext] | {elements}: elementos SysML v2 JSON (@id, @type), incluindo elementos de relacionamento. Com ext (o padrão), cada elemento traz o que json_import precisa para restaurar os registros exatamente. |
json_import | elements: um array, {elements: […]} ou versões de dados da API | {records, diagnostics}. Ids que não são UUIDs recebem UUIDs, com o original mantido em xid. Elementos de tipos que o engine não interpreta são mantidos como registros opacos que json_export grava de volta sem alteração, com uma nota json.kept-unsupported por tipo. |
v1_convert | model: um modelo SysML v1 lido de XMI pela sua integração; [check], [items] | {text, report, diagnostics?, library?}: texto SysML v2 e um relatório do que foi convertido, aproximado ou descartado. Parte do complemento de migração, licenciado separadamente. |
Conjuntos de mudanças
sync e diff respondem, e apply recebe, um array ordenado de mudanças. Criações e movimentações vêm na ordem do documento, proprietários antes dos membros; remoções vêm por último.
| Mudança | Significado |
|---|---|
{op: "create", id, fields, after?, before?} | Um novo elemento, colocado depois ou antes de um irmão, ou por último. |
{op: "update", id, patch} | Mudanças de campos; null exclui um campo. Nunca altera owner nem order. |
{op: "move", id, owner, after?, before?} | Um novo proprietário ou posição. |
{op: "remove", ids} | Remove os elementos e tudo o que eles possuem. |
Limites
Acima de um limite, o engine responde com um diagnóstico ou um código de erro, nunca travando ou falhando. Cada operação leva tempo proporcional à sua entrada.
| Limite | Valor | Acima do limite |
|---|---|---|
| Tamanho do texto | 8 MiB (UTF-8) | limit.input-size |
| Comprimento da linha | 64 KiB (UTF-8) | limit.line-length para cada linha longa |
| Aninhamento de corpos | 256 níveis | limit.nesting; a parte mais profunda é ignorada |
| Aninhamento de expressões | 512 níveis | limit.expression-depth |
| Cadeia de proprietários de registros | 512 níveis | {error: "limit.nesting"} |
| Arquivos de biblioteca, total | 64 MiB | {error: "limit.input-size"} |
| Importação JSON | 500.000 elementos | json.too-many-elements; o restante não é lido |
Modelo SysML v1 (v1_convert) | 250.000 elementos e entradas de lista; cadeias de proprietários de 512 níveis; texto de 8 MiB | {error: "limit.elements"}, {error: "limit.nesting"}, {error: "limit.output-size"} |
Novo nome em rename | 1 a 1.000 caracteres, sem caracteres de controle | {error: "rename.invalid-name"} |
O build de navegador não tem limite de tempo próprio: execute-o em um worker e encerre o worker quando ele não responder a tempo. As respostas contêm texto da entrada, como nomes e documentação; faça o escape como faria com qualquer entrada de usuário antes de colocá-lo em uma página.
Versões e estabilidade
version() informa a versão do engine e a versão da interface (abi). Dentro de uma versão principal, operações, campos e códigos de diagnóstico não são removidos nem mudam de significado; novas operações, campos e códigos podem ser adicionados, então ignore o que você não conhece. A partir da versão 2.0, uma nova versão principal é anunciada com seis meses de antecedência.
Experimente o engine nos seus próprios modelos.
A avaliação é gratuita por 60 dias e inclui o guia completo do desenvolvedor e exemplos.