@dallaylaen/ski-interpreter 2.2.1 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "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",
@@ -61,5 +61,8 @@
     "mocha": "^10.2.0",
     "nyc": "^15.1.0",
     "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
   }
 }

package/types/src/expr.d.ts

@@ -1,9 +1,77 @@
 export type TraverseValue<T_1> = T_1 | TraverseControl<T_1> | null;
 export type Partial = Expr | ((arg0: Expr) => Partial);
+/**
+ * : boolean,      // whether the irreducible form is only contains its arguments. implies normal.
+ *   arity?: number,       // the number of arguments that is sufficient to reach the normal form
+ *                         // absent unless normal.
+ *   discard?: boolean,    // whether the term (or subterms, unless proper) can discard arguments.
+ *   duplicate?: boolean,  // whether the term (or subterms, unless proper) can duplicate arguments.
+ *   skip?: Set<number>,   // indices of arguments that are discarded. nonempty inplies discard.
+ *   dup?: Set<number>,    // indices of arguments that are duplicated. nonempty implies duplicate.
+ *   expr?: Expr,          // canonical form containing lambdas, applications, and variables, if any
+ *   steps?: number,       // number of steps taken to obtain the aforementioned information, if applicable
+ * }} TermInfo
+ */
+export type proper = {
+    normal: boolean;
+};
 /**
  * @typedef {Expr | function(Expr): Partial} Partial
  */
+/**
+ * @typedef {{
+ *   normal: boolean,      // whether the term becomes irreducible after receiving a number of arguments.
+ *                         // if false, other properties may be missing.
+ *   proper: boolean,      // whether the irreducible form is only contains its arguments. implies normal.
+ *   arity?: number,       // the number of arguments that is sufficient to reach the normal form
+ *                         // absent unless normal.
+ *   discard?: boolean,    // whether the term (or subterms, unless proper) can discard arguments.
+ *   duplicate?: boolean,  // whether the term (or subterms, unless proper) can duplicate arguments.
+ *   skip?: Set<number>,   // indices of arguments that are discarded. nonempty inplies discard.
+ *   dup?: Set<number>,    // indices of arguments that are duplicated. nonempty implies duplicate.
+ *   expr?: Expr,          // canonical form containing lambdas, applications, and variables, if any
+ *   steps?: number,       // number of steps taken to obtain the aforementioned information, if applicable
+ * }} TermInfo
+ */
 export class Expr {
+    /**
+     *  @descr A combinatory logic expression.
+     *
+     *  Applications, variables, and other terms like combinators per se
+     *  are subclasses of this class.
+     *
+     *  @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 Define properties of the term based on user supplied options and/or inference results.
+     *       Typically useful for declaring Native and Alias terms.
+     * @private
+     * @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)
+     * @param {string} [options.fancy] - how to display in html mode, e.g. &phi; instead of 'f'
+     * @param {boolean} [options.canonize] - whether to try to infer the properties
+     * @param {number} [options.max] - maximum number of steps for inference, if canonize is true
+     * @param {number} [options.maxArgs] - maximum number of arguments for inference, if canonize is true
+     * @return {this}
+     */
+    private _setup;
+    fancyName: any;
+    note: any;
+    arity: any;
+    props: TermInfo;
     /**
      * @desc apply self to zero or more terms and return the resulting term,
      * without performing any calculations whatsoever
@@ -24,17 +92,46 @@ export class Expr {
     /**
      * @desc Traverse the expression tree, applying change() to each node.
      *       If change() returns an Expr, the node is replaced with that value.
-     *       Otherwise, the node is descended further (if applicable)
-     *       or left unchanged.
+     *       A null/undefined value is interpreted as
+     *       "descend further if applicable, or leave the node unchanged".
+     *
+     *       Returned values may be decorated:
      *
-     *       The traversal order is leftmost-outermost (LO), i.e. the same order as reduction steps are taken.
+     *       SKI.control.prune will suppress further descending even if nothing was returned
+     *       SKI.control.stop will terminate further changes.
+     *       SKI.control.redo will apply the callback to the returned subtree, recursively.
+     *
+     *       Note that if redo was applied at least once to a subtree, a null return from the same subtree
+     *       will be replaced by the last non-null value returned.
+     *
+     *       The traversal order is leftmost-outermost, unless options.order = 'leftmost-innermost' is specified.
+     *       Short aliases 'LO' and 'LI' (case-sensitive) are also accepted.
      *
      *       Returns null if no changes were made, or the new expression otherwise.
      *
-     * @param {(e:Expr) => (Expr|null)} change
+     * @param {{
+     *   order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost',
+     * }} [options]
+     * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {Expr|null}
      */
-    traverse(change: (e: Expr) => (Expr | null)): Expr | null;
+    traverse(options?: {
+        order?: "LO" | "LI" | "leftmost-outermost" | "leftmost-innermost";
+    }, change: (e: Expr) => TraverseValue<Expr>): Expr | null;
+    /**
+     * @private
+     * @param {Object} options
+     * @param {(e:Expr) => TraverseValue<Expr>} change
+     * @returns {TraverseValue<Expr>}
+     */
+    private _traverse_redo;
+    /**
+     * @private
+     * @param {Object} options
+     * @param {(e:Expr) => TraverseValue<Expr>} change
+     * @returns {TraverseValue<Expr>}
+     */
+    private _traverse_descend;
     /**
      * @desc Returns true if predicate() is true for any subterm of the expression, false otherwise.
      *
@@ -88,46 +185,17 @@ export class Expr {
      *       Use toLambda() if you want to get a lambda term in any case.
      *
      * @param {{max?: number, maxArgs?: number}} options
-     * @return {{
-     *    normal: boolean,
-     *    steps: number,
-     *    expr?: Expr,
-     *    arity?: number,
-     *    proper?: boolean,
-     *    discard?: boolean,
-     *    duplicate?: boolean,
-     *    skip?: Set<number>,
-     *    dup?: Set<number>,
-     * }}
+     * @return {TermInfo}
      */
     infer(options?: {
         max?: number;
         maxArgs?: number;
-    }): {
-        normal: boolean;
-        steps: number;
-        expr?: Expr;
-        arity?: number;
-        proper?: boolean;
-        discard?: boolean;
-        duplicate?: boolean;
-        skip?: Set<number>;
-        dup?: Set<number>;
-    };
+    }): TermInfo;
     /**
-     *
-     * @param {{max: number, maxArgs: number, index: number}} options
-     * @param {FreeVar[]} preArgs
-     * @param {number} steps
-     * @returns {{
-     *    normal: boolean,
-     *    steps: number,
-     *    expr?: Expr,
-     *    arity?: number,
-     *    skip?: Set<number>,
-     *    dup?: Set<number>,
-     *    duplicate, discard, proper: boolean
-     * }
+     * @desc Internal method for infer(), which performs the actual inference.
+     * @param {{max: number, maxArgs: number}} options
+     * @param {number} nargs - var index to avoid name clashes
+     * @returns {TermInfo}
      * @private
      */
     private _infer;
@@ -193,13 +261,6 @@ export class Expr {
         expr: Expr;
         steps: number;
     }>;
-    /**
-     * @desc Internal method for toSKI, which performs one step of the conversion.
-     * @param {{max: number, steps: number}} options
-     * @returns {Expr}
-     * @private
-     */
-    private _rski;
     /**
      * Replace all instances of plug in the expression with value and return the resulting expression,
      * or null if no changes could be made.
@@ -307,10 +368,14 @@ export class Expr {
     diff(other: Expr, swap?: boolean): string | null;
     /**
      * @desc Assert expression equality. Can be used in tests.
-     * @param {Expr} expected
+     *
+     * `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.
+     *
+     * @param {Expr} actual
      * @param {string} comment
      */
-    expect(expected: Expr, comment?: string): void;
+    expect(actual: Expr, comment?: string): void;
     /**
      * @desc Returns string representation of the expression.
      *       Same as format() without options.
@@ -428,33 +493,7 @@ export class App extends Expr {
     constructor(fun: Expr, arg: Expr);
     arg: Expr;
     fun: Expr;
-    final: boolean;
-    arity: number;
-    _infer(options: any, preArgs?: any[], steps?: number): {
-        normal: boolean;
-        steps: number;
-        expr?: Expr;
-        arity?: number;
-        skip?: Set<number>;
-        dup?: Set<number>;
-        duplicate: any;
-        discard: any;
-        proper: boolean;
-    } | {
-        normal: boolean;
-        steps: number;
-    } | {
-        expr: Expr;
-        arity?: number;
-        skip?: Set<number>;
-        dup?: Set<number>;
-        duplicate?: any;
-        discard?: any;
-        proper: boolean;
-        normal: boolean;
-        steps: number;
-    };
-    traverse(change: any): Expr;
+    _traverse_descend(options: any, change: any): any;
     any(predicate: any): any;
     _fold(initial: any, combine: any): any;
     subst(search: any, replace: any): Expr;
@@ -466,7 +505,7 @@ export class App extends Expr {
         steps: number;
     };
     invoke(arg: any): Partial;
-    _rski(options: any): Expr | this;
+    final: boolean;
     diff(other: any, swap?: boolean): string;
     _braced(first: any): boolean;
     _format(options: any, nargs: any): string;
@@ -496,6 +535,8 @@ export class FreeVar extends Named {
      * If a scope object is given, however, two variables with the same name and scope
      * are considered identical.
      *
+     * By convention, FreeVar.global is a constant denoting a global unbound variable.
+     *
      * @param {string} name - name of the variable
      * @param {any} scope - an object representing where the variable belongs to.
      */
@@ -505,6 +546,9 @@ export class FreeVar extends Named {
     diff(other: any, swap?: boolean): string;
     subst(search: any, replace: any): any;
 }
+export namespace FreeVar {
+    let global: string[];
+}
 export class Lambda extends Expr {
     /**
      * @desc Lambda abstraction of arg over impl.
@@ -525,26 +569,11 @@ export class Lambda extends Expr {
     arg: FreeVar;
     impl: Expr;
     arity: number;
-    _infer(options: any, preArgs?: any[], steps?: number): {
-        normal: boolean;
-        steps: number;
-        expr?: Expr;
-        arity?: number;
-        skip?: Set<number>;
-        dup?: Set<number>;
-        duplicate: any;
-        discard: any;
-        proper: boolean;
-    } | {
-        normal: boolean;
-        steps: number;
-    };
     invoke(arg: any): Expr;
-    traverse(change: any): Expr | Lambda;
+    _traverse_descend(options: any, change: any): any;
     any(predicate: any): any;
     _fold(initial: any, combine: any): any;
     subst(search: any, replace: any): Lambda;
-    _rski(options: any): any;
     diff(other: any, swap?: boolean): string;
     _format(options: any, nargs: any): string;
     _braced(first: any): boolean;
@@ -564,20 +593,14 @@ export class Native extends Named {
      *
      * @param {String} name
      * @param {Partial} impl
-     * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
+     * @param {{note?: string, arity?: number, canonize?: boolean }} [opt]
      */
     constructor(name: string, impl: Partial, opt?: {
         note?: string;
         arity?: number;
         canonize?: boolean;
-        apply?: (arg0: Expr) => (Expr | null);
     });
     invoke: Partial;
-    /** @type {number} */
-    arity: number;
-    /** @type {string} */
-    note: string;
-    _rski(options: any): Expr | this;
 }
 export class Alias extends Named {
     /**
@@ -604,43 +627,33 @@ export class Alias extends Named {
         terminal?: boolean;
     });
     impl: Expr;
-    note: string;
-    arity: any;
-    proper: any;
     terminal: any;
-    canonical: any;
     invoke: (arg: any) => any;
-    traverse(change: any): any;
+    _traverse_descend(options: any, change: any): any;
     any(predicate: any): any;
     _fold(initial: any, combine: any): any;
     subst(search: any, replace: any): any;
-    _infer(options: any, preArgs?: any[], steps?: number): {
-        normal: boolean;
-        steps: number;
-        expr?: Expr;
-        arity?: number;
-        skip?: Set<number>;
-        dup?: Set<number>;
-        duplicate: any;
-        discard: any;
-        proper: boolean;
-    };
     diff(other: any, swap?: boolean): any;
-    _rski(options: any): Expr;
     _braced(first: any): boolean;
 }
-export class Church extends Native {
+export class Church extends Expr {
     /**
      * @desc Church numeral representing non-negative integer n:
      *      n f x = f(f(...(f x)...)) with f applied n times.
      * @param {number} n
      */
     constructor(n: number);
+    invoke: (x: any) => (y: any) => any;
     /** @type {number} */
     n: number;
+    arity: number;
     diff(other: any, swap?: boolean): string;
+    _unspaced(arg: any): boolean;
+    _format(options: any, nargs: any): any;
 }
 /**
+ * @desc List of predefined native combinators.
+ * This is required for toSKI() to work, otherwise could as well have been in parser.js.
  * @type {{[key: string]: Native}}
  */
 declare const native: {

package/types/src/parser.d.ts

@@ -42,10 +42,14 @@ export class SKI {
      *
      * @param {Alias|String} term
      * @param {String|Expr|function(Expr):Partial} [impl]
-     * @param {String} [note]
+     * @param {object|string} [options]
+     * @param {string} [options.note] - optional annotation for the term, default is auto-generated if this.annotate is true
+     * @param {boolean} [options.canonize] - whether to canonize the term's implementation, default is this.annotate
+     * @param {boolean} [options.fancy] - alternative HTML-friendly name for the term
+     * @param {number} [options.arity] - custom arity for the term, default is inferred from the implementation
      * @return {SKI} chainable
      */
-    add(term: typeof classes.Alias | string, impl?: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial), note?: string): SKI;
+    add(term: typeof classes.Alias | string, impl?: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial), options?: object | string): SKI;
     /**
      * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
      * @param {Alias|string} term

package/types/src/quest.d.ts

@@ -34,6 +34,10 @@ export type QuestResult = {
     steps: number;
     weight?: number;
 };
+export type SelfCheck = {
+    accepted?: string[][];
+    rejected?: string[][];
+};
 /**
  * @typedef {{
  *   pass: boolean,
@@ -98,6 +102,9 @@ export type QuestResult = {
  *    intro?: string|string[], // multiple strings will be concatenated with spaces
  * }} QuestSpec
  */
+/**
+ * @typedef {{ accepted?: string[][], rejected?: string[][] }} SelfCheck
+ */
 export class Quest {
     /**
      * @description A combinator problem with a set of test cases for the proposed solution.
@@ -160,12 +167,39 @@ export class Quest {
      * @return {QuestResult}
      */
     check(...input: string): QuestResult;
+    verify(options: any): {
+        date: string;
+    };
+    /**
+     * @desc Verify that solutions that are expected to pass/fail do so.
+     * @param {SelfCheck|{[key: string]: SelfCheck}} dataset
+     * @return {{shouldPass: {input: string[], result: QuestResult}[], shouldFail: {input: string[], result: QuestResult}[]} | null}
+     */
+    verifySolutions(dataset: SelfCheck | {
+        [key: string]: SelfCheck;
+    }): {
+        shouldPass: {
+            input: string[];
+            result: QuestResult;
+        }[];
+        shouldFail: {
+            input: string[];
+            result: QuestResult;
+        }[];
+    } | null;
+    verifyMeta(options?: {}): {
+        date: string;
+    };
     /**
        *
        * @return {TestCase[]}
        */
     show(): TestCase[];
 }
+export namespace Quest {
+    export { Group };
+    export { Case };
+}
 declare class Case {
     /**
      * @param {FreeVar[]} input
@@ -198,6 +232,16 @@ declare class Case {
      */
     check(...expr: typeof import("./expr").Expr): CaseResult;
 }
+declare class Group {
+    constructor(options: any);
+    name: any;
+    intro: string;
+    id: any;
+    content: any;
+    verify(options: any): {
+        content: any;
+    };
+}
 import { SKI } from "./parser";
 declare class Subst {
     /**