Node.js · API

Plugin

Un plugin extiende DON.parse recorriendo cada directiva mientras se construye el árbol. Sirve para transformar argumentos (por ejemplo, resolver variables) o eliminar directivas.

interface PluginDirectiveNode {
  readonly name: string | symbol;
  readonly args: readonly (number | string | boolean | HeredocValue)[];
  readonly children?: readonly PluginDirectiveNode[];
}

interface DonPlugin<TContext = unknown> {
  readonly name: string;
  initContext?(): TContext;
  onDirective?(node: PluginDirectiveNode, ctx: TContext):
    PluginDirectiveNode | null | void;
  onEnterScope?(node: PluginDirectiveNode, ctx: TContext): void;
  onExitScope?(node: PluginDirectiveNode, ctx: TContext): void;
}

Hooks

Transformar y eliminar

import { DON, type DonPlugin } from "donly";

const upper: DonPlugin = {
  name: "upper",
  onDirective(node) {
    if (node.name === "drop") return null; // elimina la directiva
    if (node.name === "name") {
      return {
        ...node,
        args: node.args.map((a) => (typeof a === "string" ? a.toUpperCase() : a)),
      };
    }
  },
};

JSON.stringify(DON.parse('name "x"\ndrop 1\nport 1', { plugins: [upper] }));
// {"name":"X","port":1}

Orden de los hooks

const trace: DonPlugin<{ depth: number }> = {
  name: "trace",
  initContext: () => ({ depth: 0 }),
  onDirective: (node) => log.push("dir " + String(node.name)),
  onEnterScope: (node, ctx) => log.push("in " + String(node.name) + ++ctx.depth),
  onExitScope: (node, ctx) => log.push("out " + String(node.name) + ctx.depth--),
};

DON.parse("a { b { c } }\nd", { plugins: [trace] });
// dir a, in a1, dir b, in b2, dir c, in c3,
// out c3, out b2, out a1, dir d, in d1, out d1

Dónde corre un plugin

Un plugin no toca el lexer ni el parser sintáctico: actúa sobre cada nodo cuando el árbol ya está armado, justo antes de convertirlo en Directive.

texto
  → LexerParser          (texto → lista de Token)
  → SyntaxParser         (tokens → árbol de nodos sin resolver)
  → por cada nodo, en profundidad (padre antes que hijos):
      → plugin.onDirective(node, ctx)    ← aquí corren los plugins
  → Directive            (el árbol final)

Leer los tokens originales

onDirective solo ve valores ya resueltos. Para conocer el texto fuente exacto (comillas, línea y columna), lee los tokens de la Directive resultante con Directive.tokensByDirective(): primero el nombre y luego los argumentos, en orden.

const root = DON.parse('host "localhost" 8080');
const [nameToken, ...argTokens] = Directive.tokensByDirective(root)!;

nameToken.raw();       // 'host'
argTokens[0].raw();    // '"localhost"'  (con comillas)
argTokens[0].text();   // 'localhost'
argTokens[1].toJS();   // 8080
argTokens[1].span;     // posición en el texto fuente

Plugins de demostración

Son ejemplos completos para aprender a escribir un plugin, no están pensados para producción.

variablesPlugin

Desde donly/demo/plugins/variables. set nombre valor guarda el valor como string en un Map y desaparece del árbol; cualquier argumento $nombre posterior se resuelve a ese string. El set es global: a diferencia de scoped-variables, un bloque no limita su alcance.

import { DON } from "donly";
import { variablesPlugin } from "donly/demo/plugins/variables";

DON.parse("set foo 33
tar biz lol {
  bob $foo
}", {
  plugins: [variablesPlugin],
});
// {"tar":["biz","lol",{"bob":"33"}]}   (set no aparece; $foo es un string)
const ctx = new Map<string, string>();

DON.parse("set foo 33", {
  plugins: [{ ...variablesPlugin, initContext: () => ctx }],
});
ctx.get("foo"); // "33"

createResourcesPlugin

Desde donly/demo/plugins/resources. Expande resource sqlite <file-url> en hijos sintéticos (size, table y sus columns) usando PluginDirectiveNode#children. La lectura del archivo está simulada: el esquema que devuelve es fijo.

import { DON } from "donly";
import { createResourcesPlugin } from "donly/demo/plugins/resources";

const plugin = createResourcesPlugin({ cwd: process.cwd() });

DON.parse("resource sqlite file://./app.sqlite", { plugins: [plugin] });
// {"resource":["sqlite","file:///.../app.sqlite",
//   {"size":[34,"megabites"],
//    "table":[["user",{"rows":350,"columns":{...}}], ["product",{...}]]}]}
// (hijos sintéticos que el documento nunca escribió)

Plugins incluidos

scoped-variables implementa set, $nombre y ${nombre} con alcance por bloque.