tLisp

tLisp parses a small Lisp-like syntax (s-expressions) into a D3-friendly tree:

{ name: "list", children: [ ... ], meta?: { ... } }

It includes:

• ; line comments
• token capture (meta.token) on lists/atoms/errors
• error recovery with explicit €rror nodes
• a head-labeled transform for nicer visualization (list node labeled by its first child)

Note: this ZIP is production-ready as an npm package template. Before publishing, you may want to change the package name in package.json if tlisp is already taken on npm.

Install

npm i tlisp

Usage

Parse to D3 nodes

import { parseToD3 } from "tlisp";

const ast = parseToD3("(add 1 2)");
/*
ast = {
  name: "list",
  children: [
    { name: "list", children: [
      { name: "add", children: [], meta: { token: { value:"add", i:1 } } },
      { name: "1",   children: [], meta: { token: { value:"1", i:5 } } },
      { name: "2",   children: [], meta: { token: { value:"2", i:7 } } }
    ], meta: { token: { value:"(", i:0 } } }
  ]
}
*/

Comments

import { parseToD3 } from "tlisp";

parseToD3("(a b) ; ignore me\n(c d)");

Error recovery

Unmatched ) becomes an explicit €rror node by default:

import { parseToD3, ERROR_NAME, RECOVERY } from "tlisp";

const ast = parseToD3(") a");
console.log(ast.children[0].name); // "€rror"
console.log(ast.children[0].meta.reason); // "spurious_rparen"

To retain the older behavior where a recovery branch may synthesize an empty list:

parseToD3(") a", { preferErrorNodes: false });

Head-labeled transform

Turn (add 1 2) into a node named "add" with children [1,2] (great for viz):

import { parseToD3, toHeadLabeled } from "tlisp";

const root = parseToD3("(add 1 2)");
const headLabeled = toHeadLabeled(root);

If the head is itself a list, the list is labeled with the sentinel ☺.

Serialize back to source

import { d3ToString } from "tlisp";

const src = d3ToString(parseToD3("(a (b c))"));
// -> "a (b c)"

Validate a tree

import { validateD3 } from "tlisp";

const res = validateD3({ name: "list", children: [] });
if (!res.ok) console.error(res.reason);

API

Named exports:

• tokenize(input)
• parseToD3(input, { preferErrorNodes }?)
• d3ToString(node, { omitRootWrapper, onError }?)
• validateD3(node)
• visit(node, fn)
• toHeadLabeled(node, { snapshotHead, removeHeadFromChildren }?)
• helpers: makeList, makeAtom, makeError
• constants: ERROR_NAME, LIST_NAME, SENTINEL, RECOVERY

Default export: an object containing the main functions/constants.

Development

npm test
npm run build

License

MIT