@dallaylaen/ski-interpreter 2.5.0 → 2.5.2

package/lib/types/expr.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { TraverseValue, Dict } from './internal';
+import { TraverseValue } from './internal';
 /**
  * @desc Control primitives for fold() and traverse() methods.
  */
@@ -13,7 +13,7 @@ export declare const control: {
  * @desc List of predefined native combinators.
  * This is required for toSKI() to work, otherwise could as well have been in parser.js.
  */
-export declare const native: Dict<Native>;
+export declare const native: Record<string, Native>;
 export type TermInfo = {
     normal: boolean;
     proper: boolean;
@@ -54,7 +54,11 @@ export declare const FormatOptionsSchema: z.ZodObject<{
     inventory: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<Expr, Expr>>>;
 }, z.core.$strip>;
 export type FormatOptions = z.infer<typeof FormatOptionsSchema>;
-type RefinedFormatOptions = {
+/**
+ * @desc A version of FormatOptions with defaults plugged in,
+ *       use for mandatory formatImpl implementation in Expr subclasses.
+ */
+export type RefinedFormatOptions = {
     terse?: boolean;
     html?: boolean;
     brackets: [string, string];
@@ -63,54 +67,47 @@ type RefinedFormatOptions = {
     lambda: [string, string, string];
     around: [string, string];
     redex: [string, string];
-    inventory?: Dict<Expr>;
+    inventory?: Record<string, Expr>;
 };
 type TraverseOptions = {
     order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost';
 };
 type TraverseCallback = (e: Expr) => TraverseValue<Expr>;
-export declare class Expr {
-    static control: {
-        descend: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        prune: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        redo: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        stop: <T>(value?: T) => import("./internal").TraverseControl<T>;
-    };
-    static native: Dict<Native>;
+export declare abstract class Expr {
     /**
-     *  @descr A combinatory logic expression.
+     *  @desc A combinatory logic expression.
      *
-     *  Applications, variables, and other terms like combinators per se
-     *  are subclasses of this class.
+     *  Applications, variables, lambdas, combinators per se,
+     *  and other expression subtypes all extend this class.
+     *
+     *  Expr itself cannot (or at least should not) be instantiated.
      *
      *  @abstract
-     *  @property {{
-     *    scope?: any,
-     *    env?: { [key: string]: Expr },
-     *    src?: string,
-     *    parser: object,
-     *  }} [context]
-     * @property {number} [arity] - number of arguments the term is waiting for (if known)
-     * @property {string} [note] - a brief description what the term does
-     * @property {string} [fancyName] - how to display in html mode, e.g. &phi; instead of 'f'
-     *                Typically only applicable to descendants of Named.
-     * @property {TermInfo} [props] - properties inferred from the term's behavior
      */
+    /** @desc optional context for the term. Is set by the parser with addContext: true */
     context?: {
         scope?: object;
-        env?: Dict<Expr>;
+        env?: Record<string, Expr>;
         src?: string;
         parser: object;
     };
+    /** @desc number of arguments the term is waiting for (if known) */
     arity?: number;
+    /** @desc a brief description what the term does */
     note?: string;
+    /** @desc the properties of the term, typically inferred from its behavior.
+     *      This is used internally when declaring Native / Alias terms.
+     */
     props?: TermInfo;
+    /** @desc An estimated number of nodes in the expression tree.
+     *     Used to prevent runaway computations.
+     */
     size?: number;
     /**
      *
      * @desc Define properties of the term based on user supplied options and/or inference results.
      *       Typically useful for declaring Native and Alias terms.
-     * @private
+     * @protected
      * @param {Object} options
      * @param {string} [options.note] - a brief description what the term does
      * @param {number} [options.arity] - number of arguments the term is waiting for (if known)
@@ -165,17 +162,19 @@ export declare class Expr {
      * }} [options]
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {Expr|null}
+     * @final
      */
     traverse(options: TraverseOptions | TraverseCallback, change?: TraverseCallback): Expr | null;
     /**
-     * @private
+     * @protected
+     * @final
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {TraverseValue<Expr>}
      */
     _traverse_redo(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
     /**
-     * @private
+     * @protected
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {TraverseValue<Expr>}
@@ -201,13 +200,25 @@ export declare class Expr {
      *
      * This method is experimental and may change in the future.
      *
+     * @example // count the number of nodes in the expression tree
+     * expr.fold(0, (acc, e) => acc + 1);
+     *
      * @experimental
+     * @final
      * @template T
      * @param {T} initial
      * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
      * @returns {T}
      */
     fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): T;
+    /**
+     * @desc Internal method for fold(), which performs the actual folding.
+     *       Should be implemented in subclasses having any internal structure.
+     *
+     * @protected
+     * @param initial
+     * @param combine
+     */
     _fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
     /**
      * @experimental
@@ -246,6 +257,7 @@ export declare class Expr {
      *
      *       Use toLambda() if you want to get a lambda term in any case.
      *
+     * @final
      * @param {{max?: number, maxArgs?: number}} options
      * @return {TermInfo}
      */
@@ -265,7 +277,7 @@ export declare class Expr {
         max: number;
         maxArgs: number;
         maxSize: number;
-        skipNames: Dict<boolean>;
+        skipNames: Record<string, boolean>;
     }, nargs: number): TermInfo;
     /**
      * @desc Expand an expression into a list of terms
@@ -288,6 +300,7 @@ export declare class Expr {
      *
      *       See also Expr.walk() and Expr.toSKI().
      *
+     * @final
      * @param {{
      *   max?: number,
      *   maxArgs?: number,
@@ -312,6 +325,7 @@ export declare class Expr {
      *
      *     See also Expr.walk() and Expr.toLambda().
      *
+     * @final
      * @param {{max?: number}} [options]
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
@@ -321,12 +335,15 @@ export declare class Expr {
         final: boolean;
     }, void, unknown>;
     /**
-     * Replace all instances of plug in the expression with value and return the resulting expression,
+     * Replace all instances of `search` in the expression with `replace` and return the resulting expression,
      * or null if no changes could be made.
+     *
      * Lambda terms and applications will never match if used as plug
-     * as they are impossible co compare without extensive computations.
+     * as they are impossible to compare without extensive computations.
+     *
      * Typically used on variables but can also be applied to other terms, e.g. aliases.
-     * See also Expr.traverse().
+     * See also Expr.traverse() for more flexible replacement of subterms.
+     *
      * @param {Expr} search
      * @param {Expr} replace
      * @return {Expr|null}
@@ -361,6 +378,7 @@ export declare class Expr {
      * @desc Run uninterrupted sequence of step() applications
      *       until the expression is irreducible, or max number of steps is reached.
      *       Default number of steps = 1000.
+     * @final
      * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
      * @param {Expr} args
      * @return {{expr: Expr, steps: number, final: boolean}}
@@ -368,7 +386,9 @@ export declare class Expr {
     run(opt?: RunOptions | Expr, ...args: Expr[]): Run;
     /**
      * Execute step() while possible, yielding a brief description of events after each step.
+     *
      * Mnemonics: like run() but slower.
+     * @final
      * @param {{max?: number}} options
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
@@ -386,6 +406,7 @@ export declare class Expr {
      *
      * @param {Expr} other
      * @return {boolean}
+     * @final
      */
     equals(other: Expr): boolean;
     /**
@@ -402,6 +423,8 @@ export declare class Expr {
      *       To somewhat alleviate confusion, the output will include
      *       the internal id of the variable in square brackets.
      *
+     *       Do not rely on the exact format of the output as it may change in the future.
+     *
      * @example  "K(S != I)" is the result of comparing "KS" and "KI"
      * @example  "S(K([x[13] != x[14]]))K"
      *
@@ -416,6 +439,11 @@ export declare class Expr {
      * `this` is the expected value and the argument is the actual one.
      * Mnemonic: the expected value is always a combinator, the actual one may be anything.
      *
+     * In case of failure, an error is thrown with a message describing the first point of difference
+     * and `expected` and `actual` properties like in AssertionError.
+     * AssertionError is not used directly to because browsers don't recognize it.
+     *
+     * @final
      * @param {Expr} actual
      * @param {string} comment
      */
@@ -423,27 +451,32 @@ export declare class Expr {
     /**
      * @desc Returns string representation of the expression.
      *       Same as format() without options.
+     *
+     *       Use formatImpl() to override in subclasses.
      * @return {string}
+     * @final
      */
     toString(): string;
     /**
      * @desc Whether the expression needs parentheses when printed.
      * @param {boolean} [first] - whether this is the first term in a sequence
      * @return {boolean}
+     * @protected
      */
     _braced(_first?: boolean): boolean;
     /**
      * @desc Whether the expression can be printed without a space when followed by arg.
      * @param {Expr} arg
      * @returns {boolean}
-     * @private
+     * @protected
      */
     _unspaced(arg: Expr): boolean;
     /**
      * @desc    Stringify the expression with fancy formatting options.
      *          Said options mostly include wrappers around various constructs in form of ['(', ')'],
-     *          as well as terse and html flags that set up the defaults.
+     *          as well as `terse` and `html` flags that fill in appropriate defaults.
      *          Format without options is equivalent to toString() and can be parsed back.
+     * @final
      *
      * @param   {Object} [options]  - formatting options
      * @param   {boolean} [options.terse]   - whether to use terse formatting (omitting unnecessary spaces and parentheses)
@@ -478,9 +511,10 @@ export declare class Expr {
      * @param {Object} options
      * @param {number} nargs
      * @returns {string}
-     * @private
+     * @protected
+     * @abstract
      */
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    abstract formatImpl(options: RefinedFormatOptions, nargs: number): string;
     /**
      * @desc Returns a string representation of the expression tree, with indentation to show structure.
      *
@@ -502,10 +536,11 @@ export declare class Expr {
      *       FreeVar: x[54]
      *       FreeVar: x[54]
      */
-    diag(): string;
+    diag(indent?: string): string;
     /**
      * @desc Convert the expression to a JSON-serializable format.
      * @returns {string}
+     * @final
      */
     toJSON(): string | object;
 }
@@ -533,7 +568,8 @@ export declare class App extends Expr {
     unroll(): Expr[];
     diff(other: Expr, swap?: boolean): string | null;
     _braced(first?: boolean): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     _unspaced(arg: Expr): boolean;
 }
 export declare class Named extends Expr {
@@ -546,7 +582,7 @@ export declare class Named extends Expr {
     fancyName?: string;
     constructor(name: string);
     _unspaced(arg: Expr): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
 export declare class FreeVar extends Named {
     /**
@@ -571,7 +607,8 @@ export declare class FreeVar extends Named {
     constructor(name: string, scope?: object);
     diff(other: Expr, swap?: boolean): string | null;
     subst(search: Expr, replace: Expr): Expr | null;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     static global: string[];
 }
 export declare class Native extends Named {
@@ -622,7 +659,8 @@ export declare class Lambda extends Expr {
     _fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
     subst(search: Expr, replace: Expr): Expr | null;
     diff(other: Expr, swap?: boolean): string | null;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     _braced(first: boolean): boolean;
 }
 export declare class Church extends Expr {
@@ -635,7 +673,7 @@ export declare class Church extends Expr {
     constructor(n: number);
     diff(other: Expr, swap?: boolean): string | null;
     _unspaced(arg: Expr): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
 export declare class Alias extends Named {
     /**
@@ -684,7 +722,8 @@ export declare class Alias extends Named {
     step(): Step;
     diff(other: Expr, swap?: boolean): string | null;
     _braced(first: boolean): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
 }
 export declare const classes: {
     Expr: typeof Expr;

package/lib/types/index.d.ts

@@ -3,7 +3,7 @@ import { Parser } from './parser';
 import { Quest } from './quest';
 import { toposort } from './toposort';
 export declare class SKI extends Parser {
-    static native: import("./internal").Dict<import("./expr").Native>;
+    static native: Record<string, import("./expr").Native>;
     static control: {
         descend: <T>(value?: T) => import("./internal").TraverseControl<T>;
         prune: <T>(value?: T) => import("./internal").TraverseControl<T>;
@@ -39,6 +39,17 @@ export declare class SKI extends Parser {
     static K: import("./expr").Native;
     static S: import("./expr").Native;
     static W: import("./expr").Native;
+    /**
+   * @desc Create a proxy object that generates variables on demand,
+   *       with names corresponding to the property accessed.
+   *       Different invocations will return distinct variables,
+   *       even if with the same name.
+   *
+   * @example const {x, y, z} = SKI.vars();
+   *          x.name; // 'x'
+   *          x instanceof FreeVar; // true
+   *          x.apply(y).apply(z); // x(y)(z)
+   */
     static vars(scope?: object): {
         [key: string]: FreeVar;
     };

package/lib/types/internal.d.ts

@@ -1,6 +1,3 @@
-export type Dict<T> = {
-    [key: string]: T;
-};
 export declare class Tokenizer {
     /**
      * @desc Create a tokenizer that splits strings into tokens according to the given terms.
@@ -28,7 +25,7 @@ export declare class Tokenizer {
  */
 export declare function restrict(set: Set<string>, spec?: string): Set<string>;
 export type TraverseDecorator = <T>(value?: T) => TraverseControl<T>;
-export type TraverseValue<T> = T | TraverseControl<T> | null | undefined | void;
+export type TraverseValue<T> = TraverseControl<T | null | undefined | void> | T | null | undefined | void;
 export declare class TraverseControl<T> {
     /**
      * @desc A wrapper for values returned by fold/traverse callbacks

package/lib/types/quest.d.ts

@@ -220,7 +220,7 @@ declare class Case {
 }
 declare class Subst {
     /**
-     * @descr A placeholder object with exactly n free variables to be substituted later.
+     * @desc A placeholder object with exactly n free variables to be substituted later.
      *        Basically a poor man's lambda.
      * @param {Expr} expr
      * @param {FreeVar[]} env

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter. Supports SKI, BCKW, Church numerals, and setting up assertions ('quests') involving all of the above.",
   "keywords": [
     "combinatory logic",