kei-lisp 2.2.0 → 2.3.0

package/README.md

@@ -1,5 +1,6 @@
 # kei-lisp
 
+[![CI](https://github.com/ike-keichan/kei-lisp/actions/workflows/ci.yml/badge.svg)](https://github.com/ike-keichan/kei-lisp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/kei-lisp.svg)](https://www.npmjs.com/package/kei-lisp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
@@ -10,6 +11,7 @@ an interactive REPL, or embed it in your application as a library.
 ## Features
 
 - Common Lisp-inspired syntax (`setq`, `defun`, `let`, `cond`, ...)
+- Macros: `defmacro` with backquote/unquote (`` ` ``, `,`, `,@`) and `macroexpand`
 - CLI tool **and** embeddable library
 - ESM and CommonJS dual output with TypeScript types
 - Zero runtime dependencies
@@ -166,8 +168,8 @@ Runnable TypeScript examples live in [`examples/`](./examples/):
 
 ```sh
 pnpm build  # build the package once
-pnpm exec tsx examples/basic-eval.ts
-pnpm exec tsx examples/exit-handling.ts
+node --experimental-strip-types examples/basic-eval.ts
+node --experimental-strip-types examples/exit-handling.ts
 ```
 
 ## Reference

package/dist/cli.cjs

@@ -27,7 +27,7 @@ node_v8 = __toESM(node_v8, 1);
 let node_vm = require("node:vm");
 node_vm = __toESM(node_vm, 1);
 //#region package.json
-var version = "2.2.0";
+var version = "2.3.0";
 //#endregion
 //#region src/runtime/Table/index.ts
 /**
@@ -699,6 +699,31 @@ var Parser = class Parser extends Object {
 		return 0;
 	}
 	/**
+	* Recognizes a backquote (`` ` ``), wraps the following form into `(quasiquote form)`, and returns the token number; invoked from NextState.
+	* @return 0
+	*/
+	quasiquote() {
+		const anObject = new Cons(this.nextToken(), Cons.nil);
+		this.token = new Cons(InterpretedSymbol.of("quasiquote"), anObject);
+		return 0;
+	}
+	/**
+	* Recognizes a comma and wraps the following form into `(unquote form)`, or
+	* `(unquote-splicing form)` when the comma is immediately followed by `@`
+	* (i.e. `,@`); invoked from NextState.
+	* @return 0
+	*/
+	unquote() {
+		let aSymbol = InterpretedSymbol.of("unquote");
+		if (this.peekChar() === "@") {
+			this.nextChar();
+			aSymbol = InterpretedSymbol.of("unquote-splicing");
+		}
+		const anObject = new Cons(this.nextToken(), Cons.nil);
+		this.token = new Cons(aSymbol, anObject);
+		return 0;
+	}
+	/**
 	* Returns the token number for a quote or for a 0-origin String-type (pseudo-Character); invoked from NextState.
 	* @return the next state number
 	*/
@@ -818,7 +843,7 @@ var Parser = class Parser extends Object {
 		aTable.set(String(41), this.nextState(-1, null));
 		aTable.set(String(42), this.nextState(8, "symbolToken"));
 		aTable.set(String(43), this.nextState(7, "sign"));
-		aTable.set(String(44), this.nextState(8, "symbolToken"));
+		aTable.set(String(44), this.nextState(0, "unquote"));
 		aTable.set(String(45), this.nextState(7, "sign"));
 		aTable.set(String(46), this.nextState(-1, null));
 		aTable.set(String(47), this.nextState(8, "symbolToken"));
@@ -830,7 +855,7 @@ var Parser = class Parser extends Object {
 		aTable.set(String(93), this.nextState(-1, null));
 		aTable.set(String(94), this.nextState(8, "symbolToken"));
 		aTable.set(String(95), this.nextState(8, "symbolToken"));
-		aTable.set(String(96), this.nextState(0, "quote"));
+		aTable.set(String(96), this.nextState(0, "quasiquote"));
 		for (const index of IntStream.rangeClosed(97, 122)) aTable.set(String(index), this.nextState(8, "symbolToken"));
 		aTable.set(String(123), this.nextState(-1, "parseList"));
 		aTable.set(String(124), this.nextState(8, "symbolToken"));
@@ -2879,6 +2904,11 @@ var Evaluator = class Evaluator extends Object {
 	*/
 	static buildInFunctions = Evaluator.setup();
 	/**
+	* Marker symbol stored as the car of the Cons that represents a macro binding,
+	* distinguishing macros from ordinary `lambda` closures in the environment.
+	*/
+	static macroMarker = InterpretedSymbol.of("macro");
+	/**
 	* The variable binding environment used during evaluation.
 	*/
 	environment;
@@ -3024,6 +3054,85 @@ var Evaluator = class Evaluator extends Object {
 		return variable;
 	}
 	/**
+	* Implementation of the Lisp `defmacro` special form. Defines a macro: a
+	* transformer whose body receives its arguments unevaluated and returns a
+	* form that is then evaluated in the caller's environment.
+	* @param aCons the argument Cons containing the macro name, parameter list, and body
+	* @return the macro name symbol
+	*/
+	defmacro(aCons) {
+		const variable = aCons.car;
+		const lambda = Evaluator.eval(new Cons(InterpretedSymbol.of("lambda"), aCons.cdr), new Table(this.environment), this.streamManager, this.depth, this.plugins);
+		const macro = new Cons(Evaluator.macroMarker, new Cons(lambda, Cons.nil));
+		this.environment.set(variable, macro);
+		return variable;
+	}
+	/**
+	* Returns the macro transformer (a lambda Cons) bound to the given symbol, or
+	* null when the symbol is not bound to a macro. Special-form symbols are never
+	* treated as macros.
+	* @param car the operator position of a call form
+	* @return the macro's lambda Cons, or null
+	*/
+	lookupMacro(car) {
+		if (Cons.isNotSymbol(car) || Evaluator.buildInFunctions.has(car)) return null;
+		const value = this.environment.get(car);
+		if (Cons.isCons(value) && value.car === Evaluator.macroMarker) return value.nth(2);
+		return null;
+	}
+	/**
+	* Expands a macro call exactly once by applying its transformer to the
+	* unevaluated argument forms in the macro's captured environment.
+	* @param form the call form whose car names the macro
+	* @param macroLambda the macro's transformer lambda Cons
+	* @return the expansion form
+	*/
+	expandMacro1(form, macroLambda) {
+		const capturedEnvironment = macroLambda.last().car;
+		return Applier.apply(macroLambda, form.cdr, capturedEnvironment, this.streamManager, this.depth, this.plugins);
+	}
+	/**
+	* Expands a macro call once and evaluates the resulting form in the current
+	* environment.
+	* @param form the call form whose car names the macro
+	* @param macroLambda the macro's transformer lambda Cons
+	* @return the result of evaluating the expansion
+	*/
+	evalMacroCall(form, macroLambda) {
+		const expansion = this.expandMacro1(form, macroLambda);
+		return Evaluator.eval(expansion, this.environment, this.streamManager, this.depth, this.plugins);
+	}
+	/**
+	* Implementation of the Lisp `macroexpand-1` special form. Evaluates its
+	* argument to obtain a form and, when that form is a macro call, expands it
+	* exactly once without evaluating the result.
+	* @param aCons the argument Cons whose car evaluates to the form to expand
+	* @return the once-expanded form, or the form unchanged when it is not a macro call
+	*/
+	macroexpand_1(aCons) {
+		const form = Evaluator.eval(aCons.car, this.environment, this.streamManager, this.depth, this.plugins);
+		if (Cons.isNotCons(form)) return form;
+		const macroLambda = this.lookupMacro(form.car);
+		if (macroLambda == null) return form;
+		return this.expandMacro1(form, macroLambda);
+	}
+	/**
+	* Implementation of the Lisp `macroexpand` special form. Evaluates its
+	* argument to obtain a form and repeatedly expands it until the result is no
+	* longer a macro call, without evaluating the result.
+	* @param aCons the argument Cons whose car evaluates to the form to expand
+	* @return the fully expanded form
+	*/
+	macroexpand(aCons) {
+		let form = Evaluator.eval(aCons.car, this.environment, this.streamManager, this.depth, this.plugins);
+		while (Cons.isCons(form)) {
+			const macroLambda = this.lookupMacro(form.car);
+			if (macroLambda == null) break;
+			form = this.expandMacro1(form, macroLambda);
+		}
+		return form;
+	}
+	/**
 	* Implementation of the Lisp `do` special form (parallel binding update).
 	* @param aCons the argument Cons containing bindings, termination clause, and body
 	* @return the value of the termination clause's result form
@@ -3135,6 +3244,10 @@ var Evaluator = class Evaluator extends Object {
 		if (Cons.isNil(form) || Cons.isNotList(form)) return form;
 		const formCons = form;
 		if (Cons.isSymbol(formCons.car) && Evaluator.buildInFunctions.has(formCons.car)) return this.specialForm(formCons);
+		if (Cons.isSymbol(formCons.car)) {
+			const macroLambda = this.lookupMacro(formCons.car);
+			if (macroLambda != null) return this.evalMacroCall(formCons, macroLambda);
+		}
 		if (Cons.isSymbol(formCons.car) && this.plugins.length > 0) {
 			const symbol = formCons.car;
 			const plugin = this.plugins.find((p) => p.has(symbol));
@@ -3385,6 +3498,94 @@ var Evaluator = class Evaluator extends Object {
 		return aCons.car;
 	}
 	/**
+	* Implementation of the Lisp `quasiquote` (`` ` ``) special form. Returns the
+	* template with every `unquote` (`,`) and `unquote-splicing` (`,@`) at the
+	* matching nesting level replaced by the evaluation of its operand. Nested
+	* quasiquotes increase the level so inner unquotes are preserved.
+	* @param aCons the argument Cons whose car is the template
+	* @return the constructed form
+	*/
+	quasiquote(aCons) {
+		return this.quasiquoteExpand(aCons.car, 1);
+	}
+	/**
+	* Recursively expands a quasiquote template at the given nesting level.
+	* @param template the template to expand
+	* @param level the current quasiquote nesting level (1 is the outermost)
+	* @return the expanded value
+	*/
+	quasiquoteExpand(template, level) {
+		if (Cons.isNotCons(template)) return template;
+		const aCons = template;
+		if (aCons.car === InterpretedSymbol.of("unquote")) {
+			if (level === 1) return Evaluator.eval(aCons.nth(2), this.environment, this.streamManager, this.depth, this.plugins);
+			return new Cons(InterpretedSymbol.of("unquote"), new Cons(this.quasiquoteExpand(aCons.nth(2), level - 1), Cons.nil));
+		}
+		if (aCons.car === InterpretedSymbol.of("quasiquote")) return new Cons(InterpretedSymbol.of("quasiquote"), new Cons(this.quasiquoteExpand(aCons.nth(2), level + 1), Cons.nil));
+		return this.quasiquoteList(aCons, level);
+	}
+	/**
+	* Expands the elements of a quasiquoted list, handling `unquote-splicing`
+	* (`,@`) elements and a possible dotted `unquote` (`,`) tail.
+	* @param template the list template to expand
+	* @param level the current quasiquote nesting level
+	* @return the constructed list
+	*/
+	quasiquoteList(template, level) {
+		const parts = [];
+		let tail = Cons.nil;
+		let current = template;
+		while (Cons.isCons(current)) {
+			if (current.car === InterpretedSymbol.of("unquote")) {
+				tail = this.quasiquoteExpand(current, level);
+				current = Cons.nil;
+				break;
+			}
+			const head = current.car;
+			if (Cons.isCons(head) && head.car === InterpretedSymbol.of("unquote-splicing")) if (level === 1) this.spliceInto(parts, Evaluator.eval(head.nth(2), this.environment, this.streamManager, this.depth, this.plugins));
+			else parts.push(new Cons(InterpretedSymbol.of("unquote-splicing"), new Cons(this.quasiquoteExpand(head.nth(2), level - 1), Cons.nil)));
+			else parts.push(this.quasiquoteExpand(head, level));
+			current = current.cdr;
+		}
+		if (Cons.isNotNil(current)) tail = current;
+		let result = tail;
+		for (let index = parts.length - 1; index >= 0; index--) result = new Cons(parts[index], result);
+		return result;
+	}
+	/**
+	* Appends the elements of a spliced value (`,@`) onto the accumulator. The
+	* value must be a proper list (or nil); an atom or an improper (dotted) list
+	* is rejected rather than silently dropping the dotted tail.
+	* @param parts the accumulator of list elements
+	* @param value the value produced by an `unquote-splicing` operand
+	*/
+	spliceInto(parts, value) {
+		if (Cons.isNil(value)) return null;
+		if (Cons.isNotCons(value)) throw new EvalError(cannotApply("unquote-splicing", value));
+		let current = value;
+		while (Cons.isCons(current)) {
+			parts.push(current.car);
+			current = current.cdr;
+		}
+		if (Cons.isNotNil(current)) throw new EvalError(cannotApply("unquote-splicing", value));
+		return null;
+	}
+	/**
+	* Implementation of the Lisp `unquote` (`,`) special form. Signals an error
+	* because unquote is only meaningful inside a `quasiquote` template.
+	*/
+	unquote() {
+		throw new EvalError("unquote (\",\") is only valid inside a quasiquote (\"`\")");
+	}
+	/**
+	* Implementation of the Lisp `unquote-splicing` (`,@`) special form. Signals
+	* an error because unquote-splicing is only meaningful inside a `quasiquote`
+	* template.
+	*/
+	unquoteSplicing() {
+		throw new EvalError("unquote-splicing (\",@\") is only valid inside a quasiquote (\"`\")");
+	}
+	/**
 	* Implementation of the Lisp `rplaca` special form; destructively replaces the car of a Cons.
 	* @param args the argument Cons containing the target Cons expression and the new car value
 	* @return the modified Cons
@@ -3462,6 +3663,7 @@ var Evaluator = class Evaluator extends Object {
 				["apply", "apply_lisp"],
 				["bind", "bind"],
 				["cond", "cond"],
+				["defmacro", "defmacro"],
 				["defun", "defun"],
 				["do", "do_"],
 				["dolist", "doList"],
@@ -3473,6 +3675,8 @@ var Evaluator = class Evaluator extends Object {
 				["lambda", "lambda"],
 				["let", "let"],
 				["let*", "letStar"],
+				["macroexpand", "macroexpand"],
+				["macroexpand-1", "macroexpand_1"],
 				["not", "not"],
 				["notrace", "notrace"],
 				["or", "or"],
@@ -3481,6 +3685,7 @@ var Evaluator = class Evaluator extends Object {
 				["princ", "princ"],
 				["print", "print"],
 				["push", "push_"],
+				["quasiquote", "quasiquote"],
 				["quote", "quote"],
 				["rplaca", "rplaca"],
 				["rplacd", "rplacd"],
@@ -3490,6 +3695,8 @@ var Evaluator = class Evaluator extends Object {
 				["time", "time"],
 				["trace", "trace"],
 				["unless", "unless"],
+				["unquote", "unquote"],
+				["unquote-splicing", "unquoteSplicing"],
 				["when", "when"]
 			].map(([key, value]) => [InterpretedSymbol.of(key), value]));
 		} catch {
@@ -3684,7 +3891,7 @@ var LispInterpreter = class extends Object {
 		const aList = [];
 		const aTable = new Table();
 		aTable.setRoot(true);
-		aList.push("abs", "add", "and", "apply", "assoc", "atom", "bind", "car", "cdr", "characterp", "cond", "ceiling", "concatenate", "cons", "consp", "copy", "cos", "count", "floatp", "floor", "defun", "divide", "do", "do*", "dolist", "doublep", "elt", "eq", "equal", "eval", "evenp", "every", "exit", "exp", "expt", "find", "format", "gc", "gensym", "if", "integerp", "lambda", "let", "let*", "last", "length", "list", "listp", "mapcan", "mapcar", "max", "member", "memq", "min", "minusp", "mod", "multiply", "napier", "neq", "nequal", "not", "notrace", "nth", "null", "numberp", "oddp", "or", "pi", "plusp", "pop", "princ", "print", "progn", "push", "quote", "random", "reduce", "round", "rplaca", "rplacd", "setq", "set-allq", "sin", "some", "sort", "sqrt", "string-downcase", "string-trim", "string-upcase", "stringp", "subseq", "substring", "subtract", "symbolp", "tan", "terpri", "time", "trace", "truncate", "unless", "when", "zerop", "1+", "1-", "+", "-", "*", "/", "//", "=", "==", "~=", "~~", "<", "<=", ">", ">=");
+		aList.push("abs", "add", "and", "apply", "assoc", "atom", "bind", "car", "cdr", "characterp", "cond", "ceiling", "concatenate", "cons", "consp", "copy", "cos", "count", "floatp", "floor", "defmacro", "defun", "divide", "do", "do*", "dolist", "doublep", "elt", "eq", "equal", "eval", "evenp", "every", "exit", "exp", "expt", "find", "format", "gc", "gensym", "if", "integerp", "lambda", "let", "let*", "last", "length", "list", "listp", "macroexpand", "macroexpand-1", "mapcan", "mapcar", "max", "member", "memq", "min", "minusp", "mod", "multiply", "napier", "neq", "nequal", "not", "notrace", "nth", "null", "numberp", "oddp", "or", "pi", "plusp", "pop", "princ", "print", "progn", "push", "quasiquote", "quote", "random", "reduce", "round", "rplaca", "rplacd", "setq", "set-allq", "sin", "some", "sort", "sqrt", "string-downcase", "string-trim", "string-upcase", "stringp", "subseq", "substring", "subtract", "symbolp", "tan", "terpri", "time", "trace", "truncate", "unless", "unquote", "unquote-splicing", "when", "zerop", "1+", "1-", "+", "-", "*", "/", "//", "=", "==", "~=", "~~", "<", "<=", ">", ">=");
 		for (const each of aList) {
 			const aSymbol = InterpretedSymbol.of(each);
 			aTable.set(aSymbol, aSymbol);

package/dist/index.cjs

@@ -696,6 +696,31 @@ var Parser = class Parser extends Object {
 		return 0;
 	}
 	/**
+	* Recognizes a backquote (`` ` ``), wraps the following form into `(quasiquote form)`, and returns the token number; invoked from NextState.
+	* @return 0
+	*/
+	quasiquote() {
+		const anObject = new Cons(this.nextToken(), Cons.nil);
+		this.token = new Cons(InterpretedSymbol.of("quasiquote"), anObject);
+		return 0;
+	}
+	/**
+	* Recognizes a comma and wraps the following form into `(unquote form)`, or
+	* `(unquote-splicing form)` when the comma is immediately followed by `@`
+	* (i.e. `,@`); invoked from NextState.
+	* @return 0
+	*/
+	unquote() {
+		let aSymbol = InterpretedSymbol.of("unquote");
+		if (this.peekChar() === "@") {
+			this.nextChar();
+			aSymbol = InterpretedSymbol.of("unquote-splicing");
+		}
+		const anObject = new Cons(this.nextToken(), Cons.nil);
+		this.token = new Cons(aSymbol, anObject);
+		return 0;
+	}
+	/**
 	* Returns the token number for a quote or for a 0-origin String-type (pseudo-Character); invoked from NextState.
 	* @return the next state number
 	*/
@@ -815,7 +840,7 @@ var Parser = class Parser extends Object {
 		aTable.set(String(41), this.nextState(-1, null));
 		aTable.set(String(42), this.nextState(8, "symbolToken"));
 		aTable.set(String(43), this.nextState(7, "sign"));
-		aTable.set(String(44), this.nextState(8, "symbolToken"));
+		aTable.set(String(44), this.nextState(0, "unquote"));
 		aTable.set(String(45), this.nextState(7, "sign"));
 		aTable.set(String(46), this.nextState(-1, null));
 		aTable.set(String(47), this.nextState(8, "symbolToken"));
@@ -827,7 +852,7 @@ var Parser = class Parser extends Object {
 		aTable.set(String(93), this.nextState(-1, null));
 		aTable.set(String(94), this.nextState(8, "symbolToken"));
 		aTable.set(String(95), this.nextState(8, "symbolToken"));
-		aTable.set(String(96), this.nextState(0, "quote"));
+		aTable.set(String(96), this.nextState(0, "quasiquote"));
 		for (const index of IntStream.rangeClosed(97, 122)) aTable.set(String(index), this.nextState(8, "symbolToken"));
 		aTable.set(String(123), this.nextState(-1, "parseList"));
 		aTable.set(String(124), this.nextState(8, "symbolToken"));
@@ -2876,6 +2901,11 @@ var Evaluator = class Evaluator extends Object {
 	*/
 	static buildInFunctions = Evaluator.setup();
 	/**
+	* Marker symbol stored as the car of the Cons that represents a macro binding,
+	* distinguishing macros from ordinary `lambda` closures in the environment.
+	*/
+	static macroMarker = InterpretedSymbol.of("macro");
+	/**
 	* The variable binding environment used during evaluation.
 	*/
 	environment;
@@ -3021,6 +3051,85 @@ var Evaluator = class Evaluator extends Object {
 		return variable;
 	}
 	/**
+	* Implementation of the Lisp `defmacro` special form. Defines a macro: a
+	* transformer whose body receives its arguments unevaluated and returns a
+	* form that is then evaluated in the caller's environment.
+	* @param aCons the argument Cons containing the macro name, parameter list, and body
+	* @return the macro name symbol
+	*/
+	defmacro(aCons) {
+		const variable = aCons.car;
+		const lambda = Evaluator.eval(new Cons(InterpretedSymbol.of("lambda"), aCons.cdr), new Table(this.environment), this.streamManager, this.depth, this.plugins);
+		const macro = new Cons(Evaluator.macroMarker, new Cons(lambda, Cons.nil));
+		this.environment.set(variable, macro);
+		return variable;
+	}
+	/**
+	* Returns the macro transformer (a lambda Cons) bound to the given symbol, or
+	* null when the symbol is not bound to a macro. Special-form symbols are never
+	* treated as macros.
+	* @param car the operator position of a call form
+	* @return the macro's lambda Cons, or null
+	*/
+	lookupMacro(car) {
+		if (Cons.isNotSymbol(car) || Evaluator.buildInFunctions.has(car)) return null;
+		const value = this.environment.get(car);
+		if (Cons.isCons(value) && value.car === Evaluator.macroMarker) return value.nth(2);
+		return null;
+	}
+	/**
+	* Expands a macro call exactly once by applying its transformer to the
+	* unevaluated argument forms in the macro's captured environment.
+	* @param form the call form whose car names the macro
+	* @param macroLambda the macro's transformer lambda Cons
+	* @return the expansion form
+	*/
+	expandMacro1(form, macroLambda) {
+		const capturedEnvironment = macroLambda.last().car;
+		return Applier.apply(macroLambda, form.cdr, capturedEnvironment, this.streamManager, this.depth, this.plugins);
+	}
+	/**
+	* Expands a macro call once and evaluates the resulting form in the current
+	* environment.
+	* @param form the call form whose car names the macro
+	* @param macroLambda the macro's transformer lambda Cons
+	* @return the result of evaluating the expansion
+	*/
+	evalMacroCall(form, macroLambda) {
+		const expansion = this.expandMacro1(form, macroLambda);
+		return Evaluator.eval(expansion, this.environment, this.streamManager, this.depth, this.plugins);
+	}
+	/**
+	* Implementation of the Lisp `macroexpand-1` special form. Evaluates its
+	* argument to obtain a form and, when that form is a macro call, expands it
+	* exactly once without evaluating the result.
+	* @param aCons the argument Cons whose car evaluates to the form to expand
+	* @return the once-expanded form, or the form unchanged when it is not a macro call
+	*/
+	macroexpand_1(aCons) {
+		const form = Evaluator.eval(aCons.car, this.environment, this.streamManager, this.depth, this.plugins);
+		if (Cons.isNotCons(form)) return form;
+		const macroLambda = this.lookupMacro(form.car);
+		if (macroLambda == null) return form;
+		return this.expandMacro1(form, macroLambda);
+	}
+	/**
+	* Implementation of the Lisp `macroexpand` special form. Evaluates its
+	* argument to obtain a form and repeatedly expands it until the result is no
+	* longer a macro call, without evaluating the result.
+	* @param aCons the argument Cons whose car evaluates to the form to expand
+	* @return the fully expanded form
+	*/
+	macroexpand(aCons) {
+		let form = Evaluator.eval(aCons.car, this.environment, this.streamManager, this.depth, this.plugins);
+		while (Cons.isCons(form)) {
+			const macroLambda = this.lookupMacro(form.car);
+			if (macroLambda == null) break;
+			form = this.expandMacro1(form, macroLambda);
+		}
+		return form;
+	}
+	/**
 	* Implementation of the Lisp `do` special form (parallel binding update).
 	* @param aCons the argument Cons containing bindings, termination clause, and body
 	* @return the value of the termination clause's result form
@@ -3132,6 +3241,10 @@ var Evaluator = class Evaluator extends Object {
 		if (Cons.isNil(form) || Cons.isNotList(form)) return form;
 		const formCons = form;
 		if (Cons.isSymbol(formCons.car) && Evaluator.buildInFunctions.has(formCons.car)) return this.specialForm(formCons);
+		if (Cons.isSymbol(formCons.car)) {
+			const macroLambda = this.lookupMacro(formCons.car);
+			if (macroLambda != null) return this.evalMacroCall(formCons, macroLambda);
+		}
 		if (Cons.isSymbol(formCons.car) && this.plugins.length > 0) {
 			const symbol = formCons.car;
 			const plugin = this.plugins.find((p) => p.has(symbol));
@@ -3382,6 +3495,94 @@ var Evaluator = class Evaluator extends Object {
 		return aCons.car;
 	}
 	/**
+	* Implementation of the Lisp `quasiquote` (`` ` ``) special form. Returns the
+	* template with every `unquote` (`,`) and `unquote-splicing` (`,@`) at the
+	* matching nesting level replaced by the evaluation of its operand. Nested
+	* quasiquotes increase the level so inner unquotes are preserved.
+	* @param aCons the argument Cons whose car is the template
+	* @return the constructed form
+	*/
+	quasiquote(aCons) {
+		return this.quasiquoteExpand(aCons.car, 1);
+	}
+	/**
+	* Recursively expands a quasiquote template at the given nesting level.
+	* @param template the template to expand
+	* @param level the current quasiquote nesting level (1 is the outermost)
+	* @return the expanded value
+	*/
+	quasiquoteExpand(template, level) {
+		if (Cons.isNotCons(template)) return template;
+		const aCons = template;
+		if (aCons.car === InterpretedSymbol.of("unquote")) {
+			if (level === 1) return Evaluator.eval(aCons.nth(2), this.environment, this.streamManager, this.depth, this.plugins);
+			return new Cons(InterpretedSymbol.of("unquote"), new Cons(this.quasiquoteExpand(aCons.nth(2), level - 1), Cons.nil));
+		}
+		if (aCons.car === InterpretedSymbol.of("quasiquote")) return new Cons(InterpretedSymbol.of("quasiquote"), new Cons(this.quasiquoteExpand(aCons.nth(2), level + 1), Cons.nil));
+		return this.quasiquoteList(aCons, level);
+	}
+	/**
+	* Expands the elements of a quasiquoted list, handling `unquote-splicing`
+	* (`,@`) elements and a possible dotted `unquote` (`,`) tail.
+	* @param template the list template to expand
+	* @param level the current quasiquote nesting level
+	* @return the constructed list
+	*/
+	quasiquoteList(template, level) {
+		const parts = [];
+		let tail = Cons.nil;
+		let current = template;
+		while (Cons.isCons(current)) {
+			if (current.car === InterpretedSymbol.of("unquote")) {
+				tail = this.quasiquoteExpand(current, level);
+				current = Cons.nil;
+				break;
+			}
+			const head = current.car;
+			if (Cons.isCons(head) && head.car === InterpretedSymbol.of("unquote-splicing")) if (level === 1) this.spliceInto(parts, Evaluator.eval(head.nth(2), this.environment, this.streamManager, this.depth, this.plugins));
+			else parts.push(new Cons(InterpretedSymbol.of("unquote-splicing"), new Cons(this.quasiquoteExpand(head.nth(2), level - 1), Cons.nil)));
+			else parts.push(this.quasiquoteExpand(head, level));
+			current = current.cdr;
+		}
+		if (Cons.isNotNil(current)) tail = current;
+		let result = tail;
+		for (let index = parts.length - 1; index >= 0; index--) result = new Cons(parts[index], result);
+		return result;
+	}
+	/**
+	* Appends the elements of a spliced value (`,@`) onto the accumulator. The
+	* value must be a proper list (or nil); an atom or an improper (dotted) list
+	* is rejected rather than silently dropping the dotted tail.
+	* @param parts the accumulator of list elements
+	* @param value the value produced by an `unquote-splicing` operand
+	*/
+	spliceInto(parts, value) {
+		if (Cons.isNil(value)) return null;
+		if (Cons.isNotCons(value)) throw new EvalError(cannotApply("unquote-splicing", value));
+		let current = value;
+		while (Cons.isCons(current)) {
+			parts.push(current.car);
+			current = current.cdr;
+		}
+		if (Cons.isNotNil(current)) throw new EvalError(cannotApply("unquote-splicing", value));
+		return null;
+	}
+	/**
+	* Implementation of the Lisp `unquote` (`,`) special form. Signals an error
+	* because unquote is only meaningful inside a `quasiquote` template.
+	*/
+	unquote() {
+		throw new EvalError("unquote (\",\") is only valid inside a quasiquote (\"`\")");
+	}
+	/**
+	* Implementation of the Lisp `unquote-splicing` (`,@`) special form. Signals
+	* an error because unquote-splicing is only meaningful inside a `quasiquote`
+	* template.
+	*/
+	unquoteSplicing() {
+		throw new EvalError("unquote-splicing (\",@\") is only valid inside a quasiquote (\"`\")");
+	}
+	/**
 	* Implementation of the Lisp `rplaca` special form; destructively replaces the car of a Cons.
 	* @param args the argument Cons containing the target Cons expression and the new car value
 	* @return the modified Cons
@@ -3459,6 +3660,7 @@ var Evaluator = class Evaluator extends Object {
 				["apply", "apply_lisp"],
 				["bind", "bind"],
 				["cond", "cond"],
+				["defmacro", "defmacro"],
 				["defun", "defun"],
 				["do", "do_"],
 				["dolist", "doList"],
@@ -3470,6 +3672,8 @@ var Evaluator = class Evaluator extends Object {
 				["lambda", "lambda"],
 				["let", "let"],
 				["let*", "letStar"],
+				["macroexpand", "macroexpand"],
+				["macroexpand-1", "macroexpand_1"],
 				["not", "not"],
 				["notrace", "notrace"],
 				["or", "or"],
@@ -3478,6 +3682,7 @@ var Evaluator = class Evaluator extends Object {
 				["princ", "princ"],
 				["print", "print"],
 				["push", "push_"],
+				["quasiquote", "quasiquote"],
 				["quote", "quote"],
 				["rplaca", "rplaca"],
 				["rplacd", "rplacd"],
@@ -3487,6 +3692,8 @@ var Evaluator = class Evaluator extends Object {
 				["time", "time"],
 				["trace", "trace"],
 				["unless", "unless"],
+				["unquote", "unquote"],
+				["unquote-splicing", "unquoteSplicing"],
 				["when", "when"]
 			].map(([key, value]) => [InterpretedSymbol.of(key), value]));
 		} catch {
@@ -3681,7 +3888,7 @@ var LispInterpreter = class extends Object {
 		const aList = [];
 		const aTable = new Table();
 		aTable.setRoot(true);
-		aList.push("abs", "add", "and", "apply", "assoc", "atom", "bind", "car", "cdr", "characterp", "cond", "ceiling", "concatenate", "cons", "consp", "copy", "cos", "count", "floatp", "floor", "defun", "divide", "do", "do*", "dolist", "doublep", "elt", "eq", "equal", "eval", "evenp", "every", "exit", "exp", "expt", "find", "format", "gc", "gensym", "if", "integerp", "lambda", "let", "let*", "last", "length", "list", "listp", "mapcan", "mapcar", "max", "member", "memq", "min", "minusp", "mod", "multiply", "napier", "neq", "nequal", "not", "notrace", "nth", "null", "numberp", "oddp", "or", "pi", "plusp", "pop", "princ", "print", "progn", "push", "quote", "random", "reduce", "round", "rplaca", "rplacd", "setq", "set-allq", "sin", "some", "sort", "sqrt", "string-downcase", "string-trim", "string-upcase", "stringp", "subseq", "substring", "subtract", "symbolp", "tan", "terpri", "time", "trace", "truncate", "unless", "when", "zerop", "1+", "1-", "+", "-", "*", "/", "//", "=", "==", "~=", "~~", "<", "<=", ">", ">=");
+		aList.push("abs", "add", "and", "apply", "assoc", "atom", "bind", "car", "cdr", "characterp", "cond", "ceiling", "concatenate", "cons", "consp", "copy", "cos", "count", "floatp", "floor", "defmacro", "defun", "divide", "do", "do*", "dolist", "doublep", "elt", "eq", "equal", "eval", "evenp", "every", "exit", "exp", "expt", "find", "format", "gc", "gensym", "if", "integerp", "lambda", "let", "let*", "last", "length", "list", "listp", "macroexpand", "macroexpand-1", "mapcan", "mapcar", "max", "member", "memq", "min", "minusp", "mod", "multiply", "napier", "neq", "nequal", "not", "notrace", "nth", "null", "numberp", "oddp", "or", "pi", "plusp", "pop", "princ", "print", "progn", "push", "quasiquote", "quote", "random", "reduce", "round", "rplaca", "rplacd", "setq", "set-allq", "sin", "some", "sort", "sqrt", "string-downcase", "string-trim", "string-upcase", "stringp", "subseq", "substring", "subtract", "symbolp", "tan", "terpri", "time", "trace", "truncate", "unless", "unquote", "unquote-splicing", "when", "zerop", "1+", "1-", "+", "-", "*", "/", "//", "=", "==", "~=", "~~", "<", "<=", ">", ">=");
 		for (const each of aList) {
 			const aSymbol = InterpretedSymbol.of(each);
 			aTable.set(aSymbol, aSymbol);