How-to guides › Write a plugin

How-to guides

Plugins

A plugin brings a file format or a framework to archec, in one folder. It can hold three kinds of declarations:

  • a generator adds a code target: archec gen --target <id> (see generators);
  • an importer reads a file of another tool into arche-lang: archec import <file>;
  • an exporter writes the model as a file of another tool: archec export <main.arche> --format <id>.

A first plugin#

This plugin reads .kv files, where each line is NAME = number, and turns each line into a constant. It is two files in plugins/kv/, beside the project's main.arche.

plugins/kv/plugin.arche declares the importer:

importer kv "Key-value files" {
  script "import.ts"
  extensions ".kv"
}

plugins/kv/import.ts does the work:

// 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 finds the plugin by itself:

archec plugin list main.arche
kv   — plugins/kv
  importers
    kv  Key-value files — script .kv

Given a settings.kv that holds MAX_SPEED = 130 and WHEELS = 4:

archec import settings.kv -o settings.arche
✓ settings.arche — by kv (plugins/kv); 0 note(s)

settings.arche holds:

const MAX_SPEED: int32 = 130
const WHEELS:    int32 = 4

A line the script cannot read is reported at its line in the .kv file:

bad.kv:3 warning not a NAME = number line

A plugin with all three#

A larger plugin holds an importer, an exporter and a generator:

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

These are not the Arche app's plugins (plugin records, plugins.yaml). Those run in the app.

Where archec finds plugins#

Where Source Runs its code
plugins/<name>/plugin.arche beside the main file the project's own at once
a library of kind plugin that the project uses (from the Store, git or a folder) library, store once approved
ARCHE_PLUGINS, a path list of plugin folders (or folders of them) the user's at once
lib/plugins/<name>/ beside archec built in at once

When two plugins declare the same id, the nearer one wins. The project's own declarations come first, then the rows of the table in order.

A project needs no include for a plugin: uses acme "^1" is enough. A plugin's declarations are read on their own. Only two things see them: the commands that run them, and a project's generator x from <a plugin's>.

A built-in plugin's hooks (after c) do not run. What archec ships does not change every project's files.

archec plugin list [main.arche] lists the plugins: where each one comes from, and what it brings, with the options. It also says what is wrong in a plugin's own declarations. Without a project, it lists the built-in plugins and those of ./plugins.

Importers#

archec import <file> picks the importer whose extensions match the end of the file's name. The longest ending is tried first. A built-in importer keeps its own endings (.dbc, .sysml, .urdf, …). A plugin's importer takes one of them only when you name it: archec import bus.dbc --importer mydbc.

Which plugins archec import sees:

  • with --project main.arche, that project's plugins;
  • without it, the plugins of main.arche in the current folder;
  • with no main.arche there, only the built-in plugins and those of ./plugins.

So a library's plugin needs its project: --project main.arche.

A 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 and module.exports = function … work too. The script returns { files, notes, warnings, errors }:

  • files: { "path": "text" }, or [{ path, text }]. Paths are relative to the output, and never leave it.
  • notes: plain strings.
  • warnings, errors: strings, or { where, message }. where is a line of the imported file ({ line: 12 }), or a line of another file ({ file, line }).

ctx gives:

  • options: the importer's options, changed by --option k=v for a run;
  • readFile(rel), exists(rel), listFiles(rel): files beside the imported file, relative to its folder;
  • readOwn(rel): a file of the plugin's folder (its tables, its library models);
  • render(template, data), filters: the template language;
  • note(msg), warn(where, msg), error(where, msg).

What a script may read#

A script runs in the same sandbox as a generator's script. It has no process and no network. It loads no module but the plugin's own (import … from './core/view'). It can read files, and only these:

  • the imported file's folder and what is under it;
  • the plugin's own folder;
  • the folders the importer names with reads, relative to the imported file's folder. For a format whose files name other files two folders up, write reads "../..";
  • the folders given with --allow-read <dir> for one run.

A read outside these folders is an error, and so is a read through a link that leads out of them. The script cannot write files: it returns them.

A command#

importer kv "Key-value files" { command "python3 kv.py"; extensions ".kv" }

The command runs in the plugin's folder. It reads the input as JSON on its stdin: { "api": 1, "importer", "file", "name", "text", "options" }. It writes the result as JSON on its stdout. What it writes on stderr is shown as notes. A command is not sandboxed. It is code, and it is approved like a script.

What archec does with the result#

  • No -o: one file goes to stdout; several are an error.
  • -o x.arche: the one file.
  • -o folder: the files, under it.

Then archec checks what it wrote, as archec build would. It checks the main.arche written, or else the first .arche. An error there fails the import (exit 1).

Exporters#

An exporter is a generator whose files belong to another tool. It reads the same generator model (version 1). It comes as templates, a script (function generate(model, ctx)) or a command. Options, typed options, from, needs deployment and errors at an element's at all work as they do for a generator.

archec export <main.arche> --format <id> runs it. Without --format, archec picks the exporter whose extension matches the end of the -o name. -o model.json still writes the model's JSON.

  • One file: -o is that file, whatever the exporter calls it. Without -o, it goes to stdout.
  • Several files: -o is a folder.

Plugins as packages#

A Store package of kind plugin is a plugin. It holds its library.arche, its plugin.arche, and the files they need. Scripts are TypeScript (.ts): a package holds no .js. Templates may end in .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 publishes the built-in plugins as arche/<name>.

Approval#

A library's templates run as they are. Its scripts and commands run on the machine of whoever builds the project. So they run only once approved:

archec plugin approve main.arche acme            # lists its code, then records it
archec plugin approve main.arche acme --revoke

Each script or command is recorded in arche.lock, with the library's fingerprint. The entries are named acme/importer:kv, acme/exporter:kv, and acme/acme-cpp for a generator. (archec generator approve approves one generator.) When the library changes, its code is refused until it is approved again.

The project's own plugins, the user's plugins and the built-in ones need no approval.

What is checked#

The codes are the same as for generators: generator and generator-option.

  • An importer is a script or a command, not templates.
  • An importer without extensions runs only with --importer (a warning).
  • An importer or an exporter has no after, and an importer no builtins.
  • Options are held as a generator's.

Limits#

  • An importer is a script or a command; it cannot be templates.
  • An importer or an exporter has no after (it cannot be a hook).
  • A built-in plugin's hooks do not run.
  • A plugin's script reads only the folders listed above, and cannot write files.
  • A command is not sandboxed. A library's commands and scripts run only once approved.
  • A Store package of kind plugin holds no .js: its scripts are .ts.