kei-lisp 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -1,198 +1,6 @@
-import { Interface } from 'node:readline';
-
-/**
- * @class
- * @classdesc Iterator class for Cons.
- * @author Keisuke Ikeda
- * @this {Loop}
- */
-declare class Loop {
-    aCons: Cons;
-    length: number;
-    index: number;
-    /**
-     * Constructor.
-     * @param aCons the Cons to iterate over
-     */
-    constructor(aCons: Cons);
-    /**
-     * Returns this instance.
-     */
-    iterator(): this;
-    /**
-     * Returns whether a next element exists.
-     */
-    hasNext(): boolean;
-    /**
-     * Returns the next element.
-     */
-    next(): LispValue;
-    /**
-     * Implementation of the iterable protocol.
-     * Enables iteration with for...of and similar constructs.
-     */
-    [Symbol.iterator](): Iterator<LispValue>;
-    /**
-     * Implementation of the async iterable protocol.
-     * Enables iteration with for await...of and similar constructs.
-     */
-    [Symbol.asyncIterator](): AsyncIterator<LispValue>;
-    /**
-     * Advances to the next element.
-     */
-    remove(): null;
-}
-
-/**
- * @class
- * @classdesc Class that mimics a Cons cell.
- * @author Keisuke Ikeda
- * @this {Cons}
- */
-declare class Cons {
-    static readonly nil: Cons;
-    car: LispValue;
-    cdr: LispValue;
-    /**
-     * Constructor.
-     * @constructor
-     * @param car the car; defaults to nil when no argument is given.
-     * @param cdr the cdr; defaults to nil when no argument is given.
-     */
-    constructor(car?: LispValue, cdr?: LispValue);
-    /**
-     * Appends the given element to the end of this Cons.
-     * @param anObject the object to append
-     * @return the Cons with the element appended
-     */
-    add(anObject: LispValue): this;
-    /**
-     * Clones this Cons and returns the clone.
-     * @return the cloned Cons
-     */
-    clone(): Cons;
-    /**
-     * Clones the given value (a Cons element) and returns the clone.
-     * @param value a Cons element
-     * @return the cloned element
-     */
-    static cloneValue(value: LispValue): LispValue;
-    /**
-     * Returns whether this Cons equals the given object.
-     * @param anObject the object to compare against
-     * @return a boolean
-     */
-    equals(anObject: LispValue): boolean;
-    /**
-     * Returns whether both arguments are Cons cells and are equal.
-     * @param left the object to compare
-     * @param right the object to compare
-     * @return a boolean
-     */
-    equalsAUX(left: LispValue, right: LispValue): boolean;
-    /**
-     * Returns whether the given argument is an Atom.
-     */
-    static isAtom(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is a Cons.
-     */
-    static isCons(anObject: LispValue): anObject is Cons;
-    /**
-     * Returns whether the given argument is a List.
-     */
-    static isList(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is Nil.
-     */
-    static isNil(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is not a Cons.
-     */
-    static isNotCons(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is not a List.
-     */
-    static isNotList(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is not Nil.
-     */
-    static isNotNil(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is not an interpreted symbol.
-     */
-    static isNotSymbol(anObject: LispValue): boolean;
-    /**
-     * Returns whether the given argument is a number.
-     */
-    static isNumber(anObject: LispValue): anObject is number;
-    /**
-     * Returns whether the given argument is a string.
-     */
-    static isString(anObject: LispValue): anObject is string;
-    /**
-     * Returns whether the given argument is an interpreted symbol.
-     */
-    static isSymbol(anObject: LispValue): anObject is InterpretedSymbol;
-    /**
-     * Returns whether the given argument is an environment.
-     */
-    static isTable(anObject: LispValue): anObject is Table;
-    /**
-     * Returns the last cell of this Cons.
-     * @return this Cons's last cell
-     */
-    last(): Cons;
-    /**
-     * Returns an iterator over this Cons.
-     * @return an iterator over this Cons
-     */
-    loop(): Loop;
-    /**
-     * Returns the length (depth) of this Cons.
-     * @return the length (depth) of this Cons
-     */
-    length(): number;
-    /**
-     * Concatenates the given Cons and returns this Cons.
-     * @param aCons the Cons to concatenate
-     * @return this Cons
-     */
-    nconc(aCons: Cons): this;
-    /**
-     * Returns the nth element of this Cons.
-     * @param aNumber the index to retrieve
-     * @return the element at the given index
-     */
-    nth(aNumber: number): LispValue;
-    /**
-     * Lexes the given string into a Cons and returns it.
-     * @param aString the string to lex
-     */
-    static parse(aString: string): LispValue;
-    /**
-     * Sets the car.
-     */
-    setCar(anObject: LispValue): null;
-    /**
-     * Sets the cdr.
-     */
-    setCdr(anObject: LispValue): null;
-    /**
-     * Sets both the car and the cdr.
-     */
-    setCons(car: LispValue, cdr: LispValue): this;
-    /**
-     * Returns a formatted string representation of this Cons.
-     */
-    toString(): string;
-    /**
-     * Returns a formatted string representation of the given object.
-     * @param anObject the object to format
-     */
-    static toString(anObject: LispValue): string;
-}
+import { Interface } from "node:readline";
 
+//#region src/types/index.d.ts
 /**
  * Union of every value the interpreter can store or evaluate.
  *
@@ -203,7 +11,8 @@ declare class Cons {
  * - `null` — internal sentinel, distinct from Lisp `nil` (which is `Cons.nil`)
  */
 type LispValue = Cons | InterpretedSymbol | Table | number | string | null;
-
+//#endregion
+//#region src/runtime/Table/index.d.ts
 /**
  * @class
  * @classdesc Class that manages bindings of interpreted symbols.
@@ -211,158 +20,947 @@ type LispValue = Cons | InterpretedSymbol | Table | number | string | null;
  * @this {Table}
  */
 declare class Table extends Map<unknown, LispValue> {
-    source: Table | null;
-    root: boolean;
-    /**
-     * Constructor.
-     * @param aTable the environment in which this environment was created
-     */
-    constructor(aTable?: Table | null);
-    /**
-     * Clones this Table and returns the clone.
-     */
-    clone(): Table;
-    /**
-     * Returns whether anything is bound to the given property (key).
-     */
-    has(aSymbol: unknown): boolean;
-    /**
-     * Returns whether this instance equals the given object.
-     */
-    equals(anObject: unknown): boolean;
-    /**
-     * Returns the value bound to the given interpreted symbol.
-     */
-    get(aSymbol: unknown): LispValue;
-    /**
-     * Returns whether this instance is the root of the environment chain.
-     */
-    isRoot(): boolean;
-    /**
-     * Reassigns the symbol bound in the innermost scope (equivalent to Common Lisp's setq).
-     * If a binding exists in the current scope, update it and return; otherwise recurse into the parent scope.
-     */
-    setIfExist(aSymbol: unknown, anObject: LispValue): LispValue;
-    /**
-     * Sets whether this instance is the root of its environment chain.
-     */
-    setRoot(aBoolean: boolean): null;
-    /**
-     * Sets the parent environment.
-     */
-    setSource(aTable: Table | null): null;
-    /**
-     * Returns a formatted string representation of this instance.
-     */
-    toString(): string;
+  /**
+   * The enclosing (parent) environment, or null when this is the root.
+   */
+  source: Table | null;
+  /**
+   * Whether this environment is the root of its chain.
+   */
+  root: boolean;
+  /**
+   * Constructor.
+   * @constructor
+   * @param aTable the environment in which this environment was created
+   */
+  constructor(aTable?: Table | null);
+  /**
+   * Clones this Table and returns the clone.
+   * @return the cloned Table
+   */
+  clone(): Table;
+  /**
+   * Returns whether anything is bound to the given property (key).
+   * @param aSymbol the symbol to look up
+   * @return true if a binding exists in this scope or any enclosing scope
+   */
+  has(aSymbol: unknown): boolean;
+  /**
+   * Returns whether this instance equals the given object.
+   * @param anObject the object to compare against
+   * @return true when the underlying Map.equals would return true
+   */
+  equals(anObject: unknown): boolean;
+  /**
+   * Returns the value bound to the given interpreted symbol, walking up the scope chain.
+   * @param aSymbol the symbol to look up
+   * @return the bound value, or null when no binding exists
+   */
+  get(aSymbol: unknown): LispValue;
+  /**
+   * Returns whether this instance is the root of the environment chain.
+   * @return true if this is the root environment
+   */
+  isRoot(): boolean;
+  /**
+   * Reassigns the symbol bound in the innermost scope (equivalent to Common Lisp's setq). If a binding exists in the current scope, update it and return; otherwise recurse into the parent scope.
+   * @param aSymbol the symbol to update
+   * @param anObject the new bound value
+   * @return the new bound value, or null when no enclosing scope has a binding
+   */
+  setIfExist(aSymbol: unknown, anObject: LispValue): LispValue;
+  /**
+   * Sets whether this instance is the root of its environment chain.
+   * @param aBoolean the new root flag
+   * @return null
+   */
+  setRoot(aBoolean: boolean): null;
+  /**
+   * Sets the parent environment.
+   * @param aTable the new parent environment (or null)
+   * @return null
+   */
+  setSource(aTable: Table | null): null;
+  /**
+   * Returns a formatted string representation of this instance.
+   * @return the formatted string
+   */
+  toString(): string;
 }
-
+//#endregion
+//#region src/value/InterpretedSymbol/index.d.ts
 /**
  * @class
  * @classdesc Interpreted symbol with uniqueness, where each printed name maps to a single canonical instance (identity equals equality). A class that mimics canonical strings, distinct from JS's standard Symbol.
  * @author Keisuke Ikeda
  * @this {InterpretedSymbol}
  */
-declare class InterpretedSymbol {
-    #private;
-    static get table(): Table;
-    name: string;
-    /**
-     * Constructor.
-     * @param name printed name
-     */
-    constructor(name?: string);
-    /**
-     * Compares this interpreted symbol with the given one by printed name.
-     * @param aSymbol the symbol to compare against
-     * @return the difference in string length
-     */
-    compareTo(aSymbol: InterpretedSymbol): number;
-    /**
-     * Returns whether this symbol equals the given object.
-     */
-    equals(anObject: unknown): boolean;
-    /**
-     * Returns the same interpreted symbol for a given printed name.
-     * @param aString printed name
-     */
-    static of(aString: string): InterpretedSymbol;
-    /**
-     * Returns the string representation of this symbol.
-     */
-    toString(): string;
+declare class InterpretedSymbol extends Object {
+  #private;
+  /**
+   * Lazy accessor for the intern table that holds every InterpretedSymbol instance.
+   * @return the intern Table (created on first access)
+   */
+  static get table(): Table;
+  /**
+   * The printed name of this symbol.
+   */
+  name: string;
+  /**
+   * Constructor.
+   * @constructor
+   * @param name printed name
+   */
+  constructor(name?: string);
+  /**
+   * Compares this interpreted symbol with the given one by printed name.
+   * @param aSymbol the symbol to compare against
+   * @return the difference in string length
+   */
+  compareTo(aSymbol: InterpretedSymbol): number;
+  /**
+   * Returns whether this symbol equals the given object.
+   * @param anObject the object to compare against
+   * @return true when identity-equal (since intern guarantees uniqueness)
+   */
+  equals(anObject: unknown): boolean;
+  /**
+   * Returns the same interpreted symbol for a given printed name.
+   * @param aString printed name
+   * @return the canonical InterpretedSymbol for that name
+   */
+  static of(aString: string): InterpretedSymbol;
+  /**
+   * Returns the string representation of this symbol.
+   * @return the printed name
+   */
+  toString(): string;
 }
-
+//#endregion
+//#region src/value/Loop/index.d.ts
+/**
+ * @class
+ * @classdesc Iterator class for Cons.
+ * @author Keisuke Ikeda
+ * @this {Loop}
+ */
+declare class Loop extends Object {
+  /**
+   * The Cons being iterated over.
+   */
+  aCons: Cons;
+  /**
+   * The number of elements in the underlying Cons (computed once at construction time).
+   */
+  length: number;
+  /**
+   * The 1-based index of the next element to return.
+   */
+  index: number;
+  /**
+   * Constructor.
+   * @constructor
+   * @param aCons the Cons to iterate over
+   */
+  constructor(aCons: Cons);
+  /**
+   * Returns this instance so it can be used as its own iterator.
+   * @return this Loop instance
+   */
+  iterator(): this;
+  /**
+   * Returns whether a next element exists.
+   * @return true if there is at least one more element
+   */
+  hasNext(): boolean;
+  /**
+   * Returns the next element and advances the cursor.
+   * @return the element at the current index
+   */
+  next(): LispValue;
+  /**
+   * Implementation of the iterable protocol. Enables iteration with for...of and similar constructs.
+   * @return an iterator over the Cons elements
+   */
+  [Symbol.iterator](): Iterator<LispValue>;
+  /**
+   * Implementation of the async iterable protocol. Enables iteration with for await...of and similar constructs.
+   * @return an async iterator over the Cons elements
+   */
+  [Symbol.asyncIterator](): AsyncIterator<LispValue>;
+  /**
+   * Advances the cursor to the next element.
+   * @return null
+   */
+  remove(): null;
+}
+//#endregion
+//#region src/value/Cons/index.d.ts
+/**
+ * @class
+ * @classdesc Class that mimics a Cons cell.
+ * @author Keisuke Ikeda
+ * @this {Cons}
+ */
+declare class Cons extends Object {
+  /**
+   * The shared empty-list sentinel. A Cons whose car and cdr are both itself, representing Lisp `nil`.
+   */
+  static readonly nil: Cons;
+  /**
+   * The head element of this Cons cell.
+   */
+  car: LispValue;
+  /**
+   * The tail of this Cons cell (typically another Cons or nil).
+   */
+  cdr: LispValue;
+  /**
+   * Constructor.
+   * @constructor
+   * @param car the car; defaults to nil when no argument is given.
+   * @param cdr the cdr; defaults to nil when no argument is given.
+   */
+  constructor(car?: LispValue, cdr?: LispValue);
+  /**
+   * Appends the given element to the end of this Cons.
+   * @param anObject the object to append
+   * @return the Cons with the element appended
+   */
+  add(anObject: LispValue): this;
+  /**
+   * Clones this Cons and returns the clone.
+   * @return the cloned Cons
+   */
+  clone(): Cons;
+  /**
+   * Clones the given value (a Cons element) and returns the clone.
+   * @param value a Cons element
+   * @return the cloned element
+   */
+  static cloneValue(value: LispValue): LispValue;
+  /**
+   * Returns whether this Cons equals the given object.
+   * @param anObject the object to compare against
+   * @return a boolean
+   */
+  equals(anObject: LispValue): boolean;
+  /**
+   * Returns whether both arguments are Cons cells and are equal.
+   * @param left the object to compare
+   * @param right the object to compare
+   * @return a boolean
+   */
+  equalsAUX(left: LispValue, right: LispValue): boolean;
+  /**
+   * Returns whether the given argument is an Atom.
+   */
+  static isAtom(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is a Cons.
+   */
+  static isCons(anObject: LispValue): anObject is Cons;
+  /**
+   * Returns whether the given argument is a List.
+   */
+  static isList(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is Nil.
+   */
+  static isNil(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is not a Cons.
+   */
+  static isNotCons(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is not a List.
+   */
+  static isNotList(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is not Nil.
+   */
+  static isNotNil(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is not an interpreted symbol.
+   */
+  static isNotSymbol(anObject: LispValue): boolean;
+  /**
+   * Returns whether the given argument is a number.
+   */
+  static isNumber(anObject: LispValue): anObject is number;
+  /**
+   * Returns whether the given argument is a string.
+   */
+  static isString(anObject: LispValue): anObject is string;
+  /**
+   * Returns whether the given argument is an interpreted symbol.
+   */
+  static isSymbol(anObject: LispValue): anObject is InterpretedSymbol;
+  /**
+   * Returns whether the given argument is an environment.
+   */
+  static isTable(anObject: LispValue): anObject is Table;
+  /**
+   * Returns the last cell of this Cons.
+   * @return this Cons's last cell
+   */
+  last(): Cons;
+  /**
+   * Returns an iterator over this Cons.
+   * @return an iterator over this Cons
+   */
+  loop(): Loop;
+  /**
+   * Returns the length (depth) of this Cons.
+   * @return the length (depth) of this Cons
+   */
+  length(): number;
+  /**
+   * Concatenates the given Cons and returns this Cons.
+   * @param aCons the Cons to concatenate
+   * @return this Cons
+   */
+  nconc(aCons: Cons): this;
+  /**
+   * Returns the nth element of this Cons.
+   * @param aNumber the index to retrieve
+   * @return the element at the given index
+   */
+  nth(aNumber: number): LispValue;
+  /**
+   * Lexes the given string into a Cons and returns it.
+   * @param aString the string to lex
+   */
+  static parse(aString: string): LispValue;
+  /**
+   * Sets the car.
+   */
+  setCar(anObject: LispValue): null;
+  /**
+   * Sets the cdr.
+   */
+  setCdr(anObject: LispValue): null;
+  /**
+   * Sets both the car and the cdr.
+   */
+  setCons(car: LispValue, cdr: LispValue): this;
+  /**
+   * Returns a formatted string representation of this Cons.
+   */
+  toString(): string;
+  /**
+   * Returns a formatted string representation of the given object.
+   * @param anObject the object to format
+   */
+  static toString(anObject: LispValue): string;
+}
+//#endregion
+//#region src/runtime/StreamManager/index.d.ts
 type Stream = NodeJS.WritableStream | null;
 /**
  * @class
- * @classdesc
+ * @classdesc Manages output streams (stdout / stderr / spy / trace) used by the interpreter.
  * @author Keisuke Ikeda
  * @this {StreamManager}
  */
-declare class StreamManager {
-    isTrace: boolean;
-    streamTable: Map<string, Stream>;
-    spyTable: Map<InterpretedSymbol, string>;
-    traceStream: Stream;
-    constructor();
-    getStream(): Stream;
-    /**
-     * Initializes the instance variables.
-     */
-    initialize(): null;
-    isSpy(aSymbol: InterpretedSymbol | null): boolean;
-    noSpy(aSymbol: InterpretedSymbol): null;
-    noTrace(): null;
-    setIsTrace(aBoolean: boolean): null;
-    setTraceStream(aStream: Stream): null;
-    spy(aSymbol: InterpretedSymbol, aString: string): null;
-    spyStream(aSymbol: InterpretedSymbol | null): Stream | string;
-    spyTable_(): Map<InterpretedSymbol, string>;
-    trace(): null;
+declare class StreamManager extends Object {
+  /**
+   * Whether tracing is currently enabled.
+   */
+  isTrace: boolean;
+  /**
+   * Map from a named stream key (e.g. "default", "stdout", "stderr") to a WritableStream.
+   */
+  streamTable: Map<string, Stream>;
+  /**
+   * Map from a spied symbol to the stream key used for that symbol's output.
+   */
+  spyTable: Map<InterpretedSymbol, string>;
+  /**
+   * The stream that receives trace output while tracing is on.
+   */
+  traceStream: Stream;
+  /**
+   * Constructor.
+   * @constructor
+   */
+  constructor();
+  /**
+   * Returns the currently selected output stream (trace stream when tracing, otherwise the default).
+   * @return the active stream, or null when none is available
+   */
+  getStream(): Stream;
+  /**
+   * Initializes the instance variables.
+   * @return null
+   */
+  initialize(): null;
+  /**
+   * Returns whether the given symbol is being spied (or whether tracing is on, in which case every symbol is "spied").
+   * @param aSymbol the symbol to check, or null
+   * @return true if the symbol is spied or tracing is on
+   */
+  isSpy(aSymbol: InterpretedSymbol | null): boolean;
+  /**
+   * Removes the given symbol from the spy table.
+   * @param aSymbol the symbol to stop spying
+   * @return null
+   */
+  noSpy(aSymbol: InterpretedSymbol): null;
+  /**
+   * Turns tracing off and clears the spy table.
+   * @return null
+   */
+  noTrace(): null;
+  /**
+   * Sets the tracing flag.
+   * @param aBoolean the new value for the tracing flag
+   * @return null
+   */
+  setIsTrace(aBoolean: boolean): null;
+  /**
+   * Sets the trace output stream.
+   * @param aStream the stream to send trace output to
+   * @return null
+   */
+  setTraceStream(aStream: Stream): null;
+  /**
+   * Registers the given symbol as spied with the given stream key.
+   * @param aSymbol the symbol to spy on
+   * @param aString the stream key (e.g. "default")
+   * @return null
+   */
+  spy(aSymbol: InterpretedSymbol, aString: string): null;
+  /**
+   * Returns the stream (or stream-key string) used for the given symbol's spy output.
+   * @param aSymbol the symbol whose spy stream is requested, or null
+   * @return the trace stream, the registered key string, or throws if none is found
+   */
+  spyStream(aSymbol: InterpretedSymbol | null): Stream | string;
+  /**
+   * Returns a copy of the spy table (defensive copy so callers do not mutate the internal map).
+   * @return a new map containing the same entries as the internal spy table
+   */
+  spyTable_(): Map<InterpretedSymbol, string>;
+  /**
+   * Turns tracing on, routing trace output to the currently active stream.
+   * @return null
+   */
+  trace(): null;
 }
-
+//#endregion
+//#region src/plugin/types.d.ts
+/**
+ * Context passed to a plugin's `apply` call. Holds the live interpreter state
+ * needed to perform recursive evaluation or to read / write the environment.
+ */
+interface PluginContext {
+  /**
+   * The current variable binding environment.
+   */
+  environment: Table;
+  /**
+   * The stream manager that owns the interpreter's I/O / spy / trace streams.
+   */
+  streamManager: StreamManager;
+  /**
+   * The current call depth (used for spy indentation).
+   */
+  depth: number;
+  /**
+   * Re-evaluates the given form using the current environment / stream manager / depth.
+   * Use this to evaluate a sub-form (e.g. when the plugin received a lambda value).
+   * @param form the form to evaluate
+   * @return the evaluation result
+   */
+  eval(form: LispValue): LispValue;
+}
+/**
+ * A kei-lisp plugin contributes additional Lisp-callable functions to the
+ * interpreter. Register one with `LispInterpreter.use(plugin)`. When the
+ * evaluator encounters `(symbol ...)` and `symbol` is not a special form,
+ * registered plugins are consulted in registration order; the first plugin
+ * whose `has(symbol)` returns true handles the call.
+ *
+ * Arguments are pre-evaluated by the interpreter before being passed to
+ * `apply`, matching the calling convention of built-in functions.
+ */
+interface KeiLispPlugin {
+  /**
+   * Plugin identifier, used for diagnostics and collision messages.
+   */
+  readonly name: string;
+  /**
+   * Returns true if this plugin handles the given symbol.
+   * @param symbol the call symbol to check
+   * @return true if `apply` should be called for this symbol
+   */
+  has(symbol: InterpretedSymbol): boolean;
+  /**
+   * Applies the plugin function to the (already-evaluated) arguments.
+   * @param symbol the call symbol
+   * @param args the evaluated argument list (a Cons, possibly Cons.nil)
+   * @param ctx the interpreter context for recursive evaluation
+   * @return the result value
+   */
+  apply(symbol: InterpretedSymbol, args: Cons, ctx: PluginContext): LispValue;
+}
+//#endregion
+//#region src/interpreter/LispInterpreter/index.d.ts
 /**
  * @class
  * @classdesc Class for the interpreter.
  * @author Keisuke Ikeda
  * @this {LispInterpreter}
  */
-declare class LispInterpreter {
-    root: Table;
-    streamManager: StreamManager;
-    rl: Interface;
-    constructor();
-    /**
-     * Starts the interpreter.
-     */
-    run(): null;
-    /**
-     * Evaluates the given list and returns the evaluation result.
-     */
-    eval(aCons: LispValue): LispValue;
-    /**
-     * Parses the source string, evaluates every expression it contains, and returns the results as an array.
-     */
-    evalAll(source: string): LispValue[];
-    /**
-     * Parses and evaluates the source string and returns the value of the last expression.
-     */
-    evalString(source: string): LispValue;
-    /**
-     * Parses the given string into a list and returns it.
-     */
-    parse(aString: string): LispValue;
-    /**
-     * Sets the given environment as the root of the environment chain.
-     */
-    setRoot(environment: Table): null;
-    /**
-     * Initializes the environment table.
-     */
-    initializeTable(): Table;
+declare class LispInterpreter extends Object {
+  /**
+   * The root (top-level) environment table, pre-populated with built-in symbols.
+   */
+  root: Table;
+  /**
+   * The stream manager that owns the interpreter's output / spy streams.
+   */
+  streamManager: StreamManager;
+  /**
+   * Registered plugins consulted by the evaluator on every call. See `use`.
+   */
+  plugins: KeiLispPlugin[];
+  /**
+   * Constructor.
+   * @constructor
+   */
+  constructor();
+  /**
+   * Registers a plugin. Subsequent `eval` calls will consult the plugin chain
+   * (in registration order, first match wins) when no special form matches a
+   * symbol, before falling through to the Applier built-ins.
+   * @param plugin the plugin to register
+   * @return this interpreter, for chaining
+   */
+  use(plugin: KeiLispPlugin): this;
+  /**
+   * Evaluates the given expression and returns the result. Throws `ParseError`,
+   * `EvalError`, or `ExitError` on failure; library users are expected to catch
+   * these (see the `KeiLispError` base class for the parse/eval family).
+   * @param aCons the expression to evaluate
+   * @return the evaluation result
+   */
+  eval(aCons: LispValue): LispValue;
+  /**
+   * Parses the source string, evaluates every expression it contains, and returns the results as an array.
+   * @param source the Lisp source string
+   * @return the array of evaluation results, one per top-level expression
+   */
+  evalAll(source: string): LispValue[];
+  /**
+   * Parses and evaluates the source string and returns the value of the last expression.
+   * @param source the Lisp source string
+   * @return the value of the last expression, or `Cons.nil` for empty input
+   */
+  evalString(source: string): LispValue;
+  /**
+   * Parses the given string into a list of top-level expressions and returns
+   * it. The result is always a `Cons` (possibly `Cons.nil` for empty input)
+   * because the source is wrapped in an outer list before parsing. Throws
+   * `ParseError` if the source cannot be parsed.
+   * @param aString the Lisp source string
+   * @return a Cons containing the parsed top-level expressions
+   */
+  parse(aString: string): Cons;
+  /**
+   * Sets the given environment as the root of the environment chain.
+   * @param environment the environment table to install as root
+   * @return null
+   */
+  setRoot(environment: Table): null;
+  /**
+   * Builds the root environment table by pre-registering every built-in symbol and the small set of bootstrap lambdas (append / butlast / nthcdr / reverse).
+   * @return the freshly initialized root environment
+   */
+  initializeTable(): Table;
 }
-
+//#endregion
+//#region src/interpreter/Repl/index.d.ts
+/**
+ * @class
+ * @classdesc Interactive REPL wrapper around LispInterpreter. Handles line accumulation, parenthesis balancing, and prompt I/O.
+ * @author Keisuke Ikeda
+ * @this {Repl}
+ */
+declare class Repl extends Object {
+  /**
+   * The underlying interpreter used to parse and evaluate user input.
+   */
+  interpreter: LispInterpreter;
+  /**
+   * The Node.js readline interface that supplies prompt I/O.
+   */
+  rl: Interface;
+  /**
+   * Constructor.
+   * @constructor
+   * @param interpreter the interpreter to evaluate input against (defaults to a fresh one)
+   */
+  constructor(interpreter?: LispInterpreter);
+  /**
+   * Starts the REPL loop.
+   * @return void
+   */
+  run(): void;
+}
+//#endregion
+//#region src/runtime/Evaluator/index.d.ts
+/**
+ * @class
+ * @classdesc Class that mimics Lisp's universal function Evaluate.
+ * @author Keisuke Ikeda
+ * @this {Evaluator}
+ */
+declare class Evaluator extends Object {
+  /**
+   * Lisp-name to method-name dispatch map for special forms.
+   */
+  static readonly buildInFunctions: Map<InterpretedSymbol, string>;
+  /**
+   * The variable binding environment used during evaluation.
+   */
+  environment: Table;
+  /**
+   * The stream manager used for trace and spy output.
+   */
+  streamManager: StreamManager;
+  /**
+   * The current call depth, used for indenting trace/spy output.
+   */
+  depth: number;
+  /**
+   * Registered plugins consulted by `eval` when no special form matches.
+   */
+  plugins: KeiLispPlugin[];
+  /**
+   * Constructor.
+   * @param aTable the variable binding environment
+   * @param aStreamManager the stream manager for trace and spy output
+   * @param aNumber the initial call depth
+   * @param plugins the plugin chain consulted before falling through to Applier
+   */
+  constructor(aTable: Table, aStreamManager: StreamManager, aNumber: number, plugins?: KeiLispPlugin[]);
+  /**
+   * Implementation of the Lisp `and` special form.
+   * @param aCons the argument Cons containing the expressions to evaluate
+   * @return nil if any expression evaluates to nil, otherwise t
+   */
+  and(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `apply` special form.
+   * @param aCons the argument Cons containing the procedure and its argument list
+   * @return the result of applying the procedure to the arguments
+   */
+  apply_lisp(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `bind` special form.
+   * @param aCons the argument Cons whose car is the symbol to look up
+   * @return the binding count for the symbol, or nil if unbound
+   */
+  bind(aCons: Cons): LispValue;
+  /**
+   * Counts the number of distinct bindings for the given symbol along the environment chain.
+   * @param aSymbol the symbol whose bindings are inspected
+   * @return the number of distinct bindings found
+   */
+  bindAUX(aSymbol: InterpretedSymbol): number;
+  /**
+   * Sequentially evaluates and binds each (symbol value) pair into the given table; used by let*.
+   * @param parameters the Cons of (symbol value) pairs to bind
+   * @param aTable the table into which the bindings are written
+   */
+  binding(parameters: Cons, aTable: Table): null;
+  /**
+   * Evaluates all (symbol value) pairs first and then writes them into the given table in parallel; used by let.
+   * @param parameters the Cons of (symbol value) pairs to bind
+   * @param aTable the table into which the bindings are written
+   */
+  bindingParallel(parameters: Cons, aTable: Table): null;
+  /**
+   * Implementation of the Lisp `cond` special form.
+   * @param aCons the argument Cons of (test consequent...) clauses
+   * @return the result of the first clause whose test is non-nil, or nil
+   */
+  cond(aCons: LispValue): LispValue;
+  /**
+   * Implementation of the Lisp `defun` special form.
+   * @param aCons the argument Cons containing the function name, parameter list, and body
+   * @return the function name symbol
+   */
+  defun(aCons: Cons): LispValue;
+  /**
+   * 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
+   */
+  do_(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `dolist` special form.
+   * @param aCons the argument Cons containing the binding clause and body
+   * @return the value of the result form
+   */
+  doList(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `do*` special form (sequential binding update).
+   * @param aCons the argument Cons containing bindings, termination clause, and body
+   * @return the value of the termination clause's result form
+   */
+  doStar(aCons: Cons): LispValue;
+  /**
+   * Evaluates a procedure call by delegating to the Applier after evaluating each argument.
+   * @param form the call form whose car is the procedure and whose cdr is the argument list
+   * @return the result of applying the procedure
+   */
+  entrustApplier(form: Cons): LispValue;
+  /**
+   * Evaluates the given form in the given environment.
+   * @param form the form to evaluate
+   * @param environment the variable binding environment
+   * @param aStreamManager the stream manager for trace and spy output
+   * @param depth the current call depth
+   * @param plugins the plugin chain consulted before falling through to Applier
+   * @return the evaluation result
+   */
+  static eval(form: LispValue, environment: Table, aStreamManager?: StreamManager, depth?: number, plugins?: KeiLispPlugin[]): LispValue;
+  /**
+   * Evaluates the given form using this Evaluator's environment.
+   * @param form the form to evaluate
+   * @return the evaluation result
+   */
+  eval(form: LispValue): LispValue;
+  /**
+   * Evaluates the argument list (the same way `entrustApplier` does), then
+   * delegates the call to the matched plugin with a context that allows
+   * recursive evaluation.
+   * @param plugin the plugin that claimed the call symbol
+   * @param form the call form whose car is the symbol and whose cdr is the argument list
+   * @return the result returned by the plugin
+   */
+  entrustPlugin(plugin: KeiLispPlugin, form: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `eval` special form.
+   * @param aCons the argument Cons whose car is the form to evaluate twice
+   * @return the result of evaluating the form
+   */
+  eval_lisp(aCons: Cons): LispValue;
+  /**
+   * Resolves the value bound to the given symbol in the current environment.
+   * @param aSymbol the symbol to resolve
+   * @return the value bound to the symbol
+   */
+  evaluateSymbol(aSymbol: InterpretedSymbol): LispValue;
+  /**
+   * Implementation of the Lisp `exit` special form; terminates the REPL by throwing an ExitError.
+   */
+  exit(): never;
+  /**
+   * Implementation of the Lisp `gc` special form; triggers garbage collection and returns memory usage.
+   * @return an association list of memory usage statistics
+   */
+  gc(): Cons;
+  /**
+   * Implementation of the Lisp `if` special form.
+   * @param aCons the argument Cons containing the test, then-form, and else-form
+   * @return the result of evaluating the selected branch
+   */
+  if_(aCons: Cons): LispValue;
+  /**
+   * Returns the indentation string used for trace and spy output at the current depth.
+   * @return the indentation string
+   */
+  indent(): string;
+  /**
+   * Returns whether the given symbol is currently being spied on.
+   * @param aSymbol the symbol to check
+   * @return a boolean
+   */
+  isSpy(aSymbol: InterpretedSymbol | null): boolean;
+  /**
+   * Implementation of the Lisp `lambda` special form; captures the current environment as a closure.
+   * @param args the argument Cons containing the parameter list and body
+   * @return a lambda form with the captured environment appended
+   */
+  lambda(args: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `let` special form (parallel binding).
+   * @param aCons the argument Cons containing bindings and body
+   * @return the value of the last body form
+   */
+  let(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `let*` special form (sequential binding).
+   * @param aCons the argument Cons containing bindings and body
+   * @return the value of the last body form
+   */
+  letStar(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `not` special form.
+   * @param aCons the argument Cons whose car is the expression to negate
+   * @return t if the expression evaluates to nil, otherwise nil
+   */
+  not(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `notrace` special form; disables tracing.
+   * @return the symbol t
+   */
+  notrace(): InterpretedSymbol;
+  /**
+   * Implementation of the Lisp `or` special form.
+   * @param aCons the argument Cons containing the expressions to evaluate
+   * @return t if any expression evaluates to non-nil, otherwise nil
+   */
+  or(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `pop` special form.
+   * @param aCons the argument Cons whose car is the symbol bound to a list
+   * @return the popped element, or nil if the binding is not a Cons
+   */
+  pop_(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `progn` special form.
+   * @param aCons the argument Cons containing the body expressions
+   * @return the value of the last body form, or nil if there are none
+   */
+  progn(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `princ` special form; writes the evaluated argument without a trailing newline.
+   * @param aCons the argument Cons whose car is the expression to print
+   * @return the printed value
+   */
+  princ(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `print` special form; writes the evaluated argument followed by a newline.
+   * @param aCons the argument Cons whose car is the expression to print
+   * @return the printed value
+   */
+  print(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `push` special form.
+   * @param aCons the argument Cons containing the value to push and the target symbol
+   * @return the new Cons stored in the symbol
+   */
+  push_(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `quote` special form.
+   * @param aCons the argument Cons whose car is the form to return unevaluated
+   * @return the quoted form
+   */
+  quote(aCons: Cons): LispValue;
+  /**
+   * 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
+   */
+  rplaca(args: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `rplacd` special form; destructively replaces the cdr of a Cons.
+   * @param args the argument Cons containing the target Cons expression and the new cdr value
+   * @return the modified Cons
+   */
+  rplacd(args: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `setq` special form; assigns values in the local environment.
+   * @param args the argument Cons containing alternating (symbol value) pairs
+   * @return the last assigned value
+   */
+  setq(args: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `set-allq` special form; assigns values in the binding's owning scope.
+   * @param args the argument Cons containing alternating (symbol value) pairs
+   * @return the last assigned value
+   */
+  set_allq(args: Cons): LispValue;
+  /**
+   * Sets the current call depth used for trace and spy indentation.
+   * @param aNumber the new depth
+   */
+  setDepth(aNumber: number): null;
+  /**
+   * Builds and returns the Lisp-name to method-name dispatch map for special forms.
+   * @return the dispatch map
+   */
+  static setup(): Map<InterpretedSymbol, string>;
+  /**
+   * Dispatches a special-form call to the corresponding method via the build-in dispatch map.
+   * @param form the form whose car is the special-form symbol
+   * @return the result of the special-form method
+   */
+  specialForm(form: Cons): LispValue;
+  /**
+   * Writes a trace/spy line to the given stream (or stdout) with the current indentation.
+   * @param aStream the destination stream, or null/string to fall back to stdout
+   * @param line the line to write
+   */
+  spyPrint(aStream: NodeJS.WritableStream | string | null, line: string): null;
+  /**
+   * Implementation of the Lisp `terpri` special form; writes a newline to stdout.
+   * @return the symbol t
+   */
+  terpri(): InterpretedSymbol;
+  /**
+   * Implementation of the Lisp `time` special form; measures evaluation time in milliseconds.
+   * @param aCons the argument Cons whose car is the form to time
+   * @return the elapsed time in milliseconds
+   */
+  time(aCons: Cons): number;
+  /**
+   * Implementation of the Lisp `trace` special form; enables tracing.
+   * @return the symbol t
+   */
+  trace(): InterpretedSymbol;
+  /**
+   * Implementation of the Lisp `unless` special form.
+   * @param aCons the argument Cons containing the test and body
+   * @return the value of the last body form if the test is nil, otherwise nil
+   */
+  unless(aCons: Cons): LispValue;
+  /**
+   * Implementation of the Lisp `when` special form.
+   * @param aCons the argument Cons containing the test and body
+   * @return the value of the last body form if the test is non-nil, otherwise nil
+   */
+  when(aCons: Cons): LispValue;
+}
+//#endregion
+//#region src/errors/KeiLispError/index.d.ts
+/**
+ * @class
+ * @classdesc Base class for all errors raised by kei-lisp during parsing or evaluation. Catch this to handle any Lisp-level failure without intercepting an unrelated runtime error or an `ExitError` (which signals a graceful `(exit)` and is intentionally not a subclass).
+ * @author Keisuke Ikeda
+ * @this {KeiLispError}
+ */
+declare class KeiLispError extends Error {
+  /**
+   * Constructor.
+   * @constructor
+   * @param message human-readable diagnostic message
+   */
+  constructor(message: string);
+}
+//#endregion
+//#region src/errors/EvalError/index.d.ts
+/**
+ * @class
+ * @classdesc Error raised when evaluation or application of a Lisp expression fails (type mismatch, unbound symbol, arity error, etc.). Subclass of `KeiLispError`.
+ * @author Keisuke Ikeda
+ * @this {EvalError}
+ */
+declare class EvalError extends KeiLispError {
+  /**
+   * Constructor.
+   * @constructor
+   * @param message human-readable diagnostic message
+   */
+  constructor(message: string);
+}
+//#endregion
+//#region src/errors/ExitError/index.d.ts
 /**
  * @class
  * @classdesc Error class representing a graceful exit triggered by a Lisp (exit) call. Catch it at the REPL or library boundary to run cleanup before terminating.
@@ -370,11 +968,28 @@ declare class LispInterpreter {
  * @this {ExitError}
  */
 declare class ExitError extends Error {
-    /**
-     * Constructor.
-     * @constructor
-     */
-    constructor();
+  /**
+   * Constructor.
+   * @constructor
+   */
+  constructor();
 }
-
-export { Cons, ExitError, InterpretedSymbol, LispInterpreter, type LispValue };
+//#endregion
+//#region src/errors/ParseError/index.d.ts
+/**
+ * @class
+ * @classdesc Error raised when the parser cannot turn a source string into an AST. Subclass of `KeiLispError`.
+ * @author Keisuke Ikeda
+ * @this {ParseError}
+ */
+declare class ParseError extends KeiLispError {
+  /**
+   * Constructor.
+   * @constructor
+   * @param message human-readable diagnostic message
+   */
+  constructor(message: string);
+}
+//#endregion
+export { Cons, EvalError, Evaluator, ExitError, InterpretedSymbol, KeiLispError, type KeiLispPlugin, LispInterpreter, type LispValue, ParseError, type PluginContext, Repl, StreamManager, Table };
+//# sourceMappingURL=index.d.ts.map