@dallaylaen/ski-interpreter 2.2.0 → 2.2.1

package/types/src/expr.d.ts

@@ -1,7 +1,4 @@
-export type ActionWrapper<T> = T | {
-    value: T | null;
-    action: string;
-} | null;
+export type TraverseValue<T_1> = T_1 | TraverseControl<T_1> | null;
 export type Partial = Expr | ((arg0: Expr) => Partial);
 /**
  * @typedef {Expr | function(Expr): Partial} Partial
@@ -19,13 +16,19 @@ export class Expr {
      * @return {Expr}
      */
     expand(): Expr;
+    /**
+     * @desc Returns true if the expression contains only free variables and applications, false otherwise.
+     * @returns {boolean}
+     */
     freeOnly(): boolean;
     /**
      * @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 left descended further (if applicable)
+     *       Otherwise, the node is descended further (if applicable)
      *       or left unchanged.
      *
+     *       The traversal order is leftmost-outermost (LO), i.e. the same order as reduction steps are taken.
+     *
      *       Returns null if no changes were made, or the new expression otherwise.
      *
      * @param {(e:Expr) => (Expr|null)} change
@@ -55,13 +58,20 @@ export class Expr {
      * @experimental
      * @template T
      * @param {T} initial
-     * @param {(acc: T, expr: Expr) => ActionWrapper<T>} combine
+     * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
      * @returns {T}
      */
-    fold<T>(initial: T, combine: (acc: T, expr: Expr) => ActionWrapper<T>): T;
-    _fold(initial: any, combine: any): any;
+    fold<T_1>(initial: T_1, combine: (acc: T_1, expr: Expr) => TraverseValue<T_1>): T_1;
     /**
-     * @desc rough estimate of the complexity of the term
+     * @template T
+     * @param {T} initial
+     * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
+     * @returns {TraverseValue<T>}
+     * @private
+     */
+    private _fold;
+    /**
+     * @desc rough estimate of the term's complexity
      * @return {number}
      */
     weight(): number;
@@ -109,7 +119,15 @@ export class Expr {
      * @param {{max: number, maxArgs: number, index: number}} options
      * @param {FreeVar[]} preArgs
      * @param {number} steps
-     * @returns {{normal: boolean, steps: number}|{normal: boolean, steps: number}|{normal: boolean, steps: number, expr: Lambda|*, arity?: *, skip?: Set<any>, dup?: Set<any>, duplicate, discard, proper: boolean}|*|{normal: boolean, steps: number}}
+     * @returns {{
+     *    normal: boolean,
+     *    steps: number,
+     *    expr?: Expr,
+     *    arity?: number,
+     *    skip?: Set<number>,
+     *    dup?: Set<number>,
+     *    duplicate, discard, proper: boolean
+     * }
      * @private
      */
     private _infer;
@@ -144,7 +162,7 @@ export class Expr {
      *   latin?: number,
      * }} options
      * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
-     * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
+     * @return {IterableIterator<{expr: Expr, steps?: number, comment?: string}>}
      */
     toLambda(options?: {
         max?: number;
@@ -155,8 +173,8 @@ export class Expr {
         latin?: number;
     }): IterableIterator<{
         expr: Expr;
-        steps: number | null;
-        comment: string | null;
+        steps?: number;
+        comment?: string;
     }>;
     /**
      * @desc Rewrite the expression into S, K, and I combinators step by step.
@@ -227,14 +245,14 @@ export 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.
-     * @param {{max: number?, steps: number?, throw: boolean?}|Expr} [opt]
+     * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
      * @param {Expr} args
      * @return {{expr: Expr, steps: number, final: boolean}}
      */
     run(opt?: {
-        max: number | null;
-        steps: number | null;
-        throw: boolean | null;
+        max?: number;
+        steps?: number;
+        throw?: boolean;
     } | Expr, ...args: Expr): {
         expr: Expr;
         steps: number;
@@ -243,11 +261,11 @@ export class Expr {
     /**
      * Execute step() while possible, yielding a brief description of events after each step.
      * Mnemonics: like run() but slower.
-     * @param {{max: number?}} options
+     * @param {{max?: number}} options
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
     walk(options?: {
-        max: number | null;
+        max?: number;
     }): IterableIterator<{
         final: boolean;
         expr: Expr;
@@ -365,6 +383,28 @@ export class Expr {
      * @private
      */
     private _format;
+    /**
+     * @desc Returns a string representation of the expression tree, with indentation to show structure.
+     *
+     *       Applications are flattened to avoid excessive nesting.
+     *       Variables include ids to distinguish different instances of the same variable name.
+     *
+     *       May be useful for debugging.
+     *
+     * @returns {string}
+     *
+     * @example
+     * > console.log(ski.parse('C 5 x (x->x x)').diag())
+     * App:
+     *   Native: C
+     *   Church: 5
+     *   FreeVar: x[53]
+     *   Lambda (x[54]):
+     *     App:
+     *       FreeVar: x[54]
+     *       FreeVar: x[54]
+     */
+    diag(): string;
     /**
      * @desc Convert the expression to a JSON-serializable format.
      * @returns {string}
@@ -390,9 +430,33 @@ export class App extends Expr {
     fun: Expr;
     final: boolean;
     arity: number;
-    _infer(options: any, preArgs?: any[], steps?: number): 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;
+    } | {
+        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;
     any(predicate: any): any;
+    _fold(initial: any, combine: any): any;
     subst(search: any, replace: any): Expr;
     /**
      * @return {{expr: Expr, steps: number}}
@@ -402,11 +466,7 @@ export class App extends Expr {
         steps: number;
     };
     invoke(arg: any): Partial;
-    /**
-     * @desc Convert the expression to SKI combinatory logic
-     * @return {Expr}
-     */
-    _rski(options: any): Expr;
+    _rski(options: any): Expr | this;
     diff(other: any, swap?: boolean): string;
     _braced(first: any): boolean;
     _format(options: any, nargs: any): string;
@@ -465,10 +525,24 @@ export class Lambda extends Expr {
     arg: FreeVar;
     impl: Expr;
     arity: number;
-    _infer(options: any, preArgs?: any[], steps?: number): 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;
+    } | {
+        normal: boolean;
+        steps: number;
+    };
     invoke(arg: any): Expr;
     traverse(change: any): Expr | Lambda;
     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;
@@ -499,8 +573,10 @@ export class Native extends Named {
         apply?: (arg0: Expr) => (Expr | null);
     });
     invoke: Partial;
-    arity: any;
-    note: any;
+    /** @type {number} */
+    arity: number;
+    /** @type {string} */
+    note: string;
     _rski(options: any): Expr | this;
 }
 export class Alias extends Named {
@@ -518,14 +594,14 @@ export class Alias extends Named {
      *
      * @param {String} name
      * @param {Expr} impl
-     * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
+     * @param {{canonize?: boolean, max?: number, maxArgs?: number, note?: string, terminal?: boolean}} [options]
      */
     constructor(name: string, impl: Expr, options?: {
-        canonize: boolean | null;
-        max: number | null;
-        maxArgs: number | null;
-        note: string | null;
-        terminal: boolean | null;
+        canonize?: boolean;
+        max?: number;
+        maxArgs?: number;
+        note?: string;
+        terminal?: boolean;
     });
     impl: Expr;
     note: string;
@@ -536,15 +612,18 @@ export class Alias extends Named {
     invoke: (arg: any) => any;
     traverse(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): any;
-    /**
-     *
-     * @return {{expr: Expr, steps: number}}
-     */
-    step(): {
-        expr: Expr;
+    _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;
@@ -557,8 +636,8 @@ export class Church extends Native {
      * @param {number} n
      */
     constructor(n: number);
-    n: any;
-    arity: number;
+    /** @type {number} */
+    n: number;
     diff(other: any, swap?: boolean): string;
 }
 /**
@@ -567,11 +646,18 @@ export class Church extends Native {
 declare const native: {
     [key: string]: Native;
 };
-declare namespace control {
-    let descend: (arg0: any) => any;
-    let prune: (arg0: any) => any;
-    let stop: (arg0: any) => any;
-}
+/**
+ * @template T
+ * @typedef {T | TraverseControl<T> | null} TraverseValue
+ */
+/**
+ * @desc Control primitives for fold() and traverse() methods.
+ * @template T
+ * @type {{[name: string]: function(T): TraverseControl<T>}}
+ */
+declare const control: {
+    [name: string]: (arg0: T) => TraverseControl<T>;
+};
 /**
  * @desc  Sort a list in such a way that dependent terms come after the (named) terms they depend on.
  *        If env is given, only terms listed there are taken into account.

package/types/src/extras.d.ts

@@ -54,5 +54,21 @@ export function search(seed: Expr[], options: {
  * @returns {any}
  */
 export function deepFormat(obj: any, options?: object): any;
-export function declare(expr: any, env: any): string;
+/**
+ * @desc  Given an expression and a hash of named terms,
+ *        return a semicolon-separated string that declares said expression
+ *        unambiguously.
+ *
+ * @example
+ * var expr = ski.parse("T=CI; V=BCT; V x y");
+ * SKI.extras.declare(expr, expr.context.env);
+ * // 'B; C; I; T=CI; V=BC(T); x=; y=; Vx y'
+ *
+ * @param {Expr} expr
+ * @param {{[s: string]: Named}} [env]
+ * @returns {string}
+ */
+export function declare(expr: Expr, env?: {
+    [s: string]: Named;
+}): string;
 import { Expr } from "./expr";

package/types/src/internal.d.ts

@@ -27,26 +27,39 @@ export function restrict(set: Set<string>, spec?: string): Set<string>;
 /**
  * @private
  * @template T
- * @param {T|ActionWrapper<T>} value
- * @returns {[T?, string|undefined]}
+ * @param {T|TraverseControl<T>|null} value
+ * @returns {[T?, function|undefined]}
  */
-export function unwrap<T>(value: T | ActionWrapper<T>): [T?, string | undefined];
+export function unwrap<T>(value: T | TraverseControl<T> | null): [T?, Function | undefined];
 /**
+ * @desc Prepare a self-referencing wrapper function for use as a fold/traverse control decorator.
+ *
+ *       If `fun` is created by `prepareWrapper`, then
+ *       unwrap(fun(x)) will always return exactly [x, fun], and the second value can be checked with ===.
+ *
+ *       An optional label can be provided for debugging purposes.
  *
  * @private
  * @template T
- * @param {string} action
- * @returns {function(T): ActionWrapper<T>}
+ * @param {string} [label]
+ * @returns {function(T): TraverseControl<T>}
  */
-export function prepareWrapper<T>(action: string): (arg0: T) => ActionWrapper<T>;
-declare class ActionWrapper {
+export function prepareWrapper<T>(label?: string): (arg0: T) => TraverseControl<T>;
+declare class TraverseControl {
     /**
+     * @desc A wrapper for values returned by fold/traverse callbacks
+     *       which instructs the traversal to alter its behavior while
+     *       retaining the value in question.
+     *
+     *       This class is instantiated internally be `SKI.control.*` functions,
+     *       and is not intended to be used directly by client code.
+     *
      * @template T
      * @param {T} value
-     * @param {string} action
+     * @param {function(T): TraverseControl<T>} decoration
      */
-    constructor(value: T, action: string);
+    constructor(value: T, decoration: (arg0: T) => TraverseControl<T>);
     value: T;
-    action: string;
+    decoration: (arg0: T) => TraverseControl<T>;
 }
 export {};

package/types/src/parser.d.ts

@@ -24,7 +24,8 @@ export class SKI {
     };
     hasNumbers: boolean;
     hasLambdas: boolean;
-    allow: any;
+    /** @type {Set<string>} */
+    allow: Set<string>;
     /**
      * @desc Declare a new term
      * If the first argument is an Alias, it is added as is.
@@ -45,16 +46,33 @@ export class SKI {
      * @return {SKI} chainable
      */
     add(term: typeof classes.Alias | string, impl?: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial), note?: string): SKI;
-    _named(term: any, impl: any): classes.Alias | classes.Native;
-    maybeAdd(name: any, impl: any): this;
+    /**
+     * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
+     * @param {Alias|string} term
+     * @param {string|Expr|function(Expr):Partial} impl
+     * @returns {Native|Alias}
+     * @private
+     */
+    private _named;
+    /**
+     * @desc Declare a new term if it is not known, otherwise just allow it.
+     *       Currently only used by quests.
+     *       Use with caution, this function may change its signature, behavior, or even be removed in the future.
+     *
+     * @experimental
+     * @param {string|Alias} name
+     * @param {string|Expr|function(Expr):Partial} impl
+     * @returns {SKI}
+     */
+    maybeAdd(name: string | typeof classes.Alias, impl: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial)): SKI;
     /**
      * @desc Declare and remove multiple terms at once
      *       term=impl adds term
      *       term= removes term
-     * @param {string[]]} list
+     * @param {string[]} list
      * @return {SKI} chainable
      */
-    bulkAdd(list: any): SKI;
+    bulkAdd(list: string[]): SKI;
     /**
      * Restrict the interpreter to given terms. Terms prepended with '+' will be added
      * and terms preceeded with '-' will be removed.
@@ -92,44 +110,46 @@ export class SKI {
      */
     declare(): string[];
     /**
-     *
+     * @template T
      * @param {string} source
      * @param {Object} [options]
      * @param {{[keys: string]: Expr}} [options.env]
-     * @param {any} [options.scope]
+     * @param {T} [options.scope]
      * @param {boolean} [options.numbers]
      * @param {boolean} [options.lambdas]
      * @param {string} [options.allow]
      * @return {Expr}
      */
-    parse(source: string, options?: {
+    parse<T_1>(source: string, options?: {
         env?: {
             [keys: string]: typeof classes.Expr;
         };
-        scope?: any;
+        scope?: T_1;
         numbers?: boolean;
         lambdas?: boolean;
         allow?: string;
     }): typeof classes.Expr;
     /**
-     *
+     * @desc Parse a single line of source code, without splitting it into declarations.
+     *       Internal, always use parse() instead.
+     * @template T
      * @param {String} source S(KI)I
      * @param {{[keys: string]: Expr}} env
      * @param {Object} [options]
      * @param {{[keys: string]: Expr}} [options.env] - unused, see 'env' argument
-     * @param {any} [options.scope]
+     * @param {T} [options.scope]
      * @param {boolean} [options.numbers]
      * @param {boolean} [options.lambdas]
      * @param {string} [options.allow]
      * @return {Expr} parsed expression
      */
-    parseLine(source: string, env?: {
+    parseLine<T_1>(source: string, env?: {
         [keys: string]: typeof classes.Expr;
     }, options?: {
         env?: {
             [keys: string]: typeof classes.Expr;
         };
-        scope?: any;
+        scope?: T_1;
         numbers?: boolean;
         lambdas?: boolean;
         allow?: string;
@@ -159,9 +179,11 @@ export namespace SKI {
      *          x instanceof FreeVar; // true
      *          x.apply(y).apply(z); // x(y)(z)
      *
+     * @template T
+     * @param {T} [scope] - optional context to bind the generated variables to
      * @return {{[key: string]: FreeVar}}
      */
-    export function vars(context?: {}): {
+    export function vars<T_1>(scope?: T_1): {
         [key: string]: typeof import("./expr").FreeVar;
     };
     /**
@@ -173,9 +195,10 @@ export namespace SKI {
     export { classes };
     export { native };
     export let control: {
-        descend: (arg0: any) => any;
-        prune: (arg0: any) => any;
-        stop: (arg0: any) => any;
+        descend: (arg0: T) => TraverseControl<T>;
+        prune: (arg0: T) => TraverseControl<T>;
+        redo: (arg0: T) => TraverseControl<T>;
+        stop: (arg0: T) => TraverseControl<T>;
     };
 }
 import classes = require("./expr");

package/types/src/quest.d.ts

@@ -1,22 +1,22 @@
 export type CaseResult = {
     pass: boolean;
-    reason: string | null;
+    reason?: string;
     steps: number;
     start: typeof import("./expr").Expr;
     found: typeof import("./expr").Expr;
     expected: typeof import("./expr").Expr;
-    note: string | null;
+    note?: string;
     args: typeof import("./expr").Expr[];
     case: Case;
 };
 export type Capability = {
-    linear: boolean | null;
-    affine: boolean | null;
-    normal: boolean | null;
-    proper: boolean | null;
-    discard: boolean | null;
-    duplicate: boolean | null;
-    arity: number | null;
+    linear?: boolean;
+    affine?: boolean;
+    normal?: boolean;
+    proper?: boolean;
+    discard?: boolean;
+    duplicate?: boolean;
+    arity?: number;
 };
 export type InputSpec = string | {
     name: string;
@@ -37,32 +37,32 @@ export type QuestResult = {
 /**
  * @typedef {{
  *   pass: boolean,
- *   reason: string?,
+ *   reason?: string,
  *   steps: number,
  *   start: Expr,
  *   found: Expr,
  *   expected: Expr,
- *   note: string?,
+ *   note?: string,
  *   args: Expr[],
  *   case: Case
  * }} CaseResult
  */
 /**
  * @typedef {{
- *   linear: boolean?,
- *   affine: boolean?,
- *   normal: boolean?,
- *   proper: boolean?,
- *   discard: boolean?,
- *   duplicate: boolean?,
- *   arity: number?,
+ *   linear?: boolean,
+ *   affine?: boolean,
+ *   normal?: boolean,
+ *   proper?: boolean,
+ *   discard?: boolean,
+ *   duplicate?: boolean,
+ *   arity?: number,
  * }} Capability
  */
 /**
  * @typedef {
  *   [string, string]
- *   | [{max: number?}, string, string]
- *   | [{caps: Capability, max: number?}, string]
+ *   | [{max?: number}, string, string]
+ *   | [{caps: Capability, max?: number}, string]
  * } TestCase
  */
 /**
@@ -79,27 +79,29 @@ export type QuestResult = {
  *   weight?: number
  * }} QuestResult
  */
+/**
+ * @typedef {{
+ *    input: InputSpec | InputSpec[],
+ *    cases: TestCase[],
+ *
+ *    // the rest is optional
+ *
+ *    allow?: string,
+ *    numbers?: boolean,
+ *    env?: string[],
+ *    engine?: SKI,
+ *    engineFull?: SKI,
+ *
+ *    // metadata, also any fields not listed here will go to quest.meta.???
+ *    id?: string|number,
+ *    name?: string,
+ *    intro?: string|string[], // multiple strings will be concatenated with spaces
+ * }} QuestSpec
+ */
 export class Quest {
     /**
      * @description A combinator problem with a set of test cases for the proposed solution.
-     * @param {{
-     *    input: InputSpec | InputSpec[],
-     *    cases: TestCase[],
-     *
-     *    // the rest is optional
-  
-     *    allow?: string,
-     *    numbers?: boolean,
-     *    env?: string[],
-     *    engine?: SKI,
-     *    engineFull?: SKI,
-     *
-     *    // metadata, also any fields not listed here will go to quest.meta.???
-     *    id?: string|number,
-     *    name?: string,
-     *    intro?: string|string[], // multiple strings will be concatenated with spaces
-     * }} options
-     *
+     * @param {QuestSpec} options
      * @example const quest = new Quest({
      *    input: 'identity',
      *    cases: [
@@ -114,11 +116,11 @@ export class Quest {
      *                       //     despite having the same name.
      * quest.check('I');     // fail! I not in the allowed list.
      */
-    constructor(options?: {});
+    constructor(options: QuestSpec);
     engine: any;
     engineFull: any;
     restrict: {
-        allow: any;
+        allow: QuestSpec;
         numbers: any;
         lambdas: any;
     };
@@ -129,7 +131,7 @@ export class Quest {
     name: any;
     intro: any;
     id: any;
-    meta: {};
+    meta: QuestSpec;
     /**
      *   Display allowed terms based on what engine thinks of this.env + this.restrict.allow
      *   @return {string}