kei-lisp 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+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;
+}
+
+/**
+ * Union of every value the interpreter can store or evaluate.
+ *
+ * - `Cons` — pairs and lists (including `Cons.nil`)
+ * - `InterpretedSymbol` — interned Lisp symbols
+ * - `Table` — environment frame (internal use)
+ * - `number` / `string` — primitive atoms
+ * - `null` — internal sentinel, distinct from Lisp `nil` (which is `Cons.nil`)
+ */
+type LispValue = Cons | InterpretedSymbol | Table | number | string | null;
+
+/**
+ * @class
+ * @classdesc Class that manages bindings of interpreted symbols.
+ * @author Keisuke Ikeda
+ * @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;
+}
+
+/**
+ * @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;
+}
+
+type Stream = NodeJS.WritableStream | null;
+/**
+ * @class
+ * @classdesc
+ * @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;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * @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.
+ * @author Keisuke Ikeda
+ * @this {ExitError}
+ */
+declare class ExitError extends Error {
+    /**
+     * Constructor.
+     * @constructor
+     */
+    constructor();
+}
+
+export { Cons, ExitError, InterpretedSymbol, LispInterpreter, type LispValue };