kei-lisp 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -20,48 +20,70 @@ type LispValue = Cons | InterpretedSymbol | Table | number | string | null;
  * @this {Table}
  */
 declare class Table extends Map<unknown, LispValue> {
+  /**
+   * 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.
+   * 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.
+   * 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;
 }
@@ -73,12 +95,20 @@ declare class Table extends Map<unknown, LispValue> {
  * @author Keisuke Ikeda
  * @this {InterpretedSymbol}
  */
-declare class InterpretedSymbol {
+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);
@@ -90,15 +120,19 @@ declare class InterpretedSymbol {
   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;
 }
@@ -110,39 +144,53 @@ declare class InterpretedSymbol {
  * @author Keisuke Ikeda
  * @this {Loop}
  */
-declare class 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.
+   * 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.
+   * 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.
+   * 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.
+   * 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 to the next element.
+   * Advances the cursor to the next element.
+   * @return null
    */
   remove(): null;
 }
@@ -154,9 +202,18 @@ declare class Loop {
  * @author Keisuke Ikeda
  * @this {Cons}
  */
-declare class 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.
@@ -302,32 +359,153 @@ declare class Cons {
 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 {
+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
@@ -335,22 +513,50 @@ declare class StreamManager {
  * @author Keisuke Ikeda
  * @this {LispInterpreter}
  */
-declare class LispInterpreter {
+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;
   /**
@@ -358,14 +564,19 @@ declare class LispInterpreter {
    * 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;
   /**
-   * Initializes the environment table.
+   * 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;
 }
@@ -377,16 +588,442 @@ declare class LispInterpreter {
  * @author Keisuke Ikeda
  * @this {Repl}
  */
-declare class 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>;
+  /**
+   * Marker symbol stored as the car of the Cons that represents a macro binding,
+   * distinguishing macros from ordinary `lambda` closures in the environment.
+   */
+  static readonly macroMarker: InterpretedSymbol;
+  /**
+   * 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 `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: Cons): LispValue;
+  /**
+   * 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: LispValue): Cons | 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: Cons, macroLambda: Cons): LispValue;
+  /**
+   * 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: Cons, macroLambda: Cons): LispValue;
+  /**
+   * 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: Cons): LispValue;
+  /**
+   * 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: 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 `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: Cons): LispValue;
+  /**
+   * 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: LispValue, level: number): LispValue;
+  /**
+   * 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: Cons, level: number): LispValue;
+  /**
+   * 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: LispValue[], value: LispValue): null;
+  /**
+   * Implementation of the Lisp `unquote` (`,`) special form. Signals an error
+   * because unquote is only meaningful inside a `quasiquote` template.
+   */
+  unquote(): never;
+  /**
+   * Implementation of the Lisp `unquote-splicing` (`,@`) special form. Signals
+   * an error because unquote-splicing is only meaningful inside a `quasiquote`
+   * template.
+   */
+  unquoteSplicing(): never;
+  /**
+   * 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
@@ -450,5 +1087,5 @@ declare class ParseError extends KeiLispError {
   constructor(message: string);
 }
 //#endregion
-export { Cons, EvalError, ExitError, InterpretedSymbol, KeiLispError, LispInterpreter, type LispValue, ParseError, Repl };
+export { Cons, EvalError, Evaluator, ExitError, InterpretedSymbol, KeiLispError, type KeiLispPlugin, LispInterpreter, type LispValue, ParseError, type PluginContext, Repl, StreamManager, Table };
 //# sourceMappingURL=index.d.cts.map