Plugins
Un plugin apporte à archec un format de fichier ou un framework, dans un seul dossier. Il peut contenir trois sortes de déclarations :
- un générateur ajoute une cible de code :
archec gen --target <id>(voir générateurs) ; - un importeur lit un fichier d’un autre outil et le fait entrer dans
arche-lang :
archec import <file>; - un exporteur écrit le modèle sous forme de fichier d’un autre outil :
archec export <main.arche> --format <id>.
Un premier plugin#
Ce plugin lit des fichiers .kv, où chaque ligne a la forme NAME = number,
et transforme chaque ligne en constante. Il tient en deux fichiers dans
plugins/kv/, à côté du main.arche du projet.
plugins/kv/plugin.arche déclare l’importeur :
importer kv "Key-value files" {
script "import.ts"
extensions ".kv"
}
plugins/kv/import.ts fait le travail :
// Each line `NAME = 12` becomes a constant.
export default function importFile(input, ctx) {
const out = [];
input.text.split('\n').forEach((line, i) => {
const m = /^(\w+)\s*=\s*(\d+)$/.exec(line.trim());
if (m) out.push(`const ${m[1]}: int32 = ${m[2]}`);
else if (line.trim()) ctx.warn({ line: i + 1 }, 'not a NAME = number line');
});
return { files: { 'settings.arche': out.join('\n') + '\n' } };
}
archec trouve le plugin tout seul :
archec plugin list main.arche
kv — plugins/kv
importers
kv Key-value files — script .kv
Avec un fichier settings.kv qui contient MAX_SPEED = 130 et WHEELS = 4 :
archec import settings.kv -o settings.arche
✓ settings.arche — by kv (plugins/kv); 0 note(s)
settings.arche contient :
const MAX_SPEED: int32 = 130
const WHEELS: int32 = 4
Une ligne que le script ne sait pas lire est signalée à sa ligne dans le
fichier .kv :
bad.kv:3 warning not a NAME = number line
Un plugin avec les trois#
Un plugin plus complet contient un importeur, un exporteur et un générateur :
plugins/acme/
library.arche library acme "Acme tools" { version "0.1.0"; kind plugin }
plugin.arche its generators, importers and exporters
kv/import.ts
kv/export.ts
cpp/generate.ts
README.md
importer kv "Key-value files" {
script "kv/import.ts"
extensions ".kv"
reads "../.."
}
exporter kv "Key-value files" {
script "kv/export.ts"
extension ".kv"
}
generator acme-cpp "Acme C++" {
script "cpp/generate.ts"
option framework "The runtime" { type string; values acme, stl; default acme }
}
archec import settings.kv -o settings.arche
archec export main.arche --format kv -o settings.kv
archec gen main.arche --target acme-cpp --option framework=stl
archec plugin list main.arche
Ce ne sont pas les plugins de l’application Arche (enregistrements plugin,
plugins.yaml). Ceux-là s’exécutent dans l’application.
Où archec trouve les plugins#
| Emplacement | Origine | Exécute son code |
|---|---|---|
plugins/<name>/plugin.arche à côté du fichier principal |
ceux du projet | immédiatement |
une bibliothèque de kind plugin que le projet utilise avec uses (depuis le Store, git ou un dossier) |
library, store |
une fois approuvé |
ARCHE_PLUGINS, une liste de chemins vers des dossiers de plugins (ou des dossiers qui en contiennent) |
ceux de l’utilisateur | immédiatement |
lib/plugins/<name>/ à côté d’archec |
intégrés | immédiatement |
Quand deux plugins déclarent le même identifiant, le plus proche l’emporte. Les déclarations propres au projet passent en premier, puis les lignes du tableau, dans l’ordre.
Un projet n’a pas besoin d’include pour un plugin : uses acme "^1"
suffit. Les déclarations d’un plugin sont lues à part. Seules deux choses les
voient : les commandes qui les exécutent, et un generator x from <a plugin's>
dans un projet.
Les hooks d’un plugin intégré (after c) ne s’exécutent pas. Ce que livre
archec ne modifie pas les fichiers de chaque projet.
archec plugin list [main.arche] liste les plugins : la provenance de
chacun, et ce qu’il apporte, avec ses options. La commande signale aussi les
problèmes dans les déclarations propres d’un plugin. Sans projet, elle liste
les plugins intégrés et ceux de ./plugins.
Importeurs#
archec import <file> choisit l’importeur dont les extensions correspondent
à la fin du nom du fichier. La terminaison la plus longue est essayée en
premier. Un importeur intégré garde ses propres terminaisons (.dbc,
.sysml, .urdf, …). L’importeur d’un plugin n’en prend une que si vous le
nommez : archec import bus.dbc --importer mydbc.
Les plugins que voit archec import :
- avec
--project main.arche, ceux de ce projet ; - sans cette option, ceux du
main.archedu dossier courant ; - en l’absence de
main.archeà cet endroit, seulement les plugins intégrés et ceux de./plugins.
Le plugin d’une bibliothèque a donc besoin de son projet : --project main.arche.
Un script#
export default function importFile(input, ctx) {
// input: { api: 1, importer, file, name, text, options }
const names = [...input.text.matchAll(/identifier="(\w+)"/g)].map((m) => m[1]);
if (!names.length) ctx.warn({ line: 1 }, 'no identifier');
return { files: { 'main.arche': names.map((n) => `component ${n}`).join('\n') + '\n' } };
}
export function importFile et module.exports = function … fonctionnent
aussi. Le script renvoie { files, notes, warnings, errors } :
files:{ "path": "text" }, ou[{ path, text }]. Les chemins sont relatifs à la sortie, et n’en sortent jamais.notes: des chaînes simples.warnings,errors: des chaînes, ou{ where, message }.whereest une ligne du fichier importé ({ line: 12 }), ou une ligne d’un autre fichier ({ file, line }).
ctx fournit :
options: les options de l’importeur, modifiées par--option k=vle temps d’une exécution ;readFile(rel),exists(rel),listFiles(rel): des fichiers à côté du fichier importé, relatifs à son dossier ;readOwn(rel): un fichier du dossier du plugin (ses tables, ses modèles de bibliothèque) ;render(template, data),filters: le langage de gabarits ;note(msg),warn(where, msg),error(where, msg).
Ce qu’un script peut lire#
Un script s’exécute dans le même bac à sable que le script d’un générateur.
Il n’a ni process ni réseau. Il ne charge aucun module en dehors de ceux du
plugin (import … from './core/view'). Il peut lire des fichiers, et
seulement ceux-ci :
- le dossier du fichier importé et ce qu’il contient ;
- le dossier propre au plugin ;
- les dossiers que l’importeur nomme avec
reads, relatifs au dossier du fichier importé. Pour un format dont les fichiers font référence à d’autres fichiers deux dossiers plus haut, écrivezreads "../.."; - les dossiers passés avec
--allow-read <dir>le temps d’une exécution.
Une lecture hors de ces dossiers est une erreur, tout comme une lecture à travers un lien qui en sort. Le script ne peut pas écrire de fichiers : il les renvoie.
Une commande#
importer kv "Key-value files" { command "python3 kv.py"; extensions ".kv" }
La commande s’exécute dans le dossier du plugin. Elle lit l’entrée en JSON
sur son entrée standard (stdin) :
{ "api": 1, "importer", "file", "name", "text", "options" }. Elle écrit le
résultat en JSON sur sa sortie standard (stdout). Ce qu’elle écrit sur stderr
est affiché sous forme de notes. Une commande n’est pas dans un bac à sable.
C’est du code, et elle est approuvée comme un script.
Ce qu’archec fait du résultat#
- Sans
-o: un seul fichier part sur stdout ; plusieurs, c’est une erreur. -o x.arche: ce fichier unique.-o folder: les fichiers, dans ce dossier.
archec vérifie ensuite ce qu’il a écrit, comme le ferait archec build. Il
vérifie le main.arche écrit, ou à défaut le premier .arche. Une erreur à
ce stade fait échouer l’import (code de sortie 1).
Exporteurs#
Un exporteur est un générateur dont les fichiers appartiennent à un autre
outil. Il lit le même modèle de générateur
(version 1). Il prend la forme de gabarits, d’un script
(function generate(model, ctx)) ou d’une commande. Les options, les options
typées, from, needs deployment et les erreurs placées sur le at d’un
élément fonctionnent comme pour un générateur.
archec export <main.arche> --format <id> l’exécute. Sans --format, archec
choisit l’exporteur dont l’extension correspond à la fin du nom passé à
-o. -o model.json écrit toujours le JSON du modèle.
- Un seul fichier :
-odésigne ce fichier, quel que soit le nom que lui donne l’exporteur. Sans-o, il part sur stdout. - Plusieurs fichiers :
-oest un dossier.
Les plugins en paquets#
Un paquet du Store de kind plugin est un plugin. Il contient son
library.arche, son plugin.arche et les fichiers dont ils ont besoin. Les
scripts sont en TypeScript (.ts) : un paquet ne contient aucun .js. Les
gabarits peuvent se terminer par .tpl.
archec store check ./acme # kind plugin needs a plugin.arche
archec add main.arche acme/acme@^0.1
archec plugin approve main.arche acme
archec store seed publie les plugins intégrés sous le nom arche/<name>.
Approbation#
Les gabarits d’une bibliothèque s’exécutent tels quels. Ses scripts et ses commandes s’exécutent sur la machine de la personne qui construit le projet. Ils ne s’exécutent donc qu’une fois approuvés :
archec plugin approve main.arche acme # lists its code, then records it
archec plugin approve main.arche acme --revoke
Chaque script ou commande est enregistré dans arche.lock, avec l’empreinte
de la bibliothèque. Les entrées s’appellent acme/importer:kv,
acme/exporter:kv, et acme/acme-cpp pour un générateur.
(archec generator approve approuve un seul générateur.) Quand la
bibliothèque change, son code est refusé jusqu’à une nouvelle approbation.
Les plugins propres au projet, ceux de l’utilisateur et les plugins intégrés n’ont pas besoin d’approbation.
Ce qui est vérifié#
Les codes sont les mêmes que pour les générateurs : generator et
generator-option.
- Un importeur est un
scriptou unecommand, pas des gabarits. - Un importeur sans
extensionsne s’exécute qu’avec--importer(un avertissement). - Un importeur ou un exporteur n’a pas d’
after, et un importeur n’a pas debuiltins. - Les options sont traitées comme celles d’un générateur.
Limites#
- Un importeur est un script ou une commande ; il ne peut pas être fait de gabarits.
- Un importeur ou un exporteur n’a pas d’
after(il ne peut pas être un hook). - Les hooks d’un plugin intégré ne s’exécutent pas.
- Le script d’un plugin ne lit que les dossiers listés plus haut, et ne peut pas écrire de fichiers.
- Une commande n’est pas dans un bac à sable. Les commandes et les scripts d’une bibliothèque ne s’exécutent qu’une fois approuvés.
- Un paquet du Store de
kind pluginne contient aucun.js: ses scripts sont en.ts.