kei-lisp 2.0.0 → 2.1.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,52 +20,53 @@ 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;
+  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;
 }
-
+//#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.
@@ -264,35 +74,231 @@ declare class Table extends Map<unknown, LispValue> {
  * @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;
+  #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;
 }
-
+//#endregion
+//#region src/value/Loop/index.d.ts
+/**
+ * @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;
+}
+//#endregion
+//#region src/value/Cons/index.d.ts
+/**
+ * @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;
+}
+//#endregion
+//#region src/runtime/StreamManager/index.d.ts
 type Stream = NodeJS.WritableStream | null;
 /**
  * @class
@@ -301,27 +307,28 @@ type Stream = NodeJS.WritableStream | null;
  * @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;
+  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;
 }
-
+//#endregion
+//#region src/interpreter/LispInterpreter/index.d.ts
 /**
  * @class
  * @classdesc Class for the interpreter.
@@ -329,40 +336,90 @@ declare class StreamManager {
  * @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;
+  root: Table;
+  streamManager: StreamManager;
+  constructor();
+  /**
+   * 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).
+   */
+  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 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.
+   */
+  parse(aString: string): Cons;
+  /**
+   * Sets the given environment as the root of the environment chain.
+   */
+  setRoot(environment: Table): null;
+  /**
+   * Initializes the environment table.
+   */
+  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 {
+  interpreter: LispInterpreter;
+  rl: Interface;
+  constructor(interpreter?: LispInterpreter);
+  /**
+   * Starts the REPL loop.
+   */
+  run(): void;
+}
+//#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 +427,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, ExitError, InterpretedSymbol, KeiLispError, LispInterpreter, type LispValue, ParseError, Repl };
+//# sourceMappingURL=index.d.ts.map