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
-
initContext(): crea el estado del plugin una vez por cadaDON.parse. Nunca se comparte con otro plugin. Sin él,ctxesundefined. -
onDirective(node, ctx): se llama una vez por directiva, de forma ordenada según el documento (el padre antes que sus hijos). El nodo no se modifica: devuelve uno nuevo para cambiarlo,nullpara eliminar la directiva con sus hijos, o nada para dejarlo igual. Si el nodo devuelto traechildren, reemplazan a los originales. -
onEnterScope(node, ctx): justo antes de visitar los hijos de la directiva. -
onExitScope(node, ctx): justo después de visitarlos. Se llama siempre que huboonEnterScope, incluso si la directiva no tiene hijos.
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.