@dallaylaen/ski-interpreter 2.2.0 → 2.3.0

package/types/src/expr.d.ts

@@ -1,12 +1,77 @@
-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);
+/**
+ * : 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
@@ -19,19 +84,54 @@ 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)
-     *       or left unchanged.
+     *       A null/undefined value is interpreted as
+     *       "descend further if applicable, or leave the node unchanged".
+     *
+     *       Returned values may be decorated:
+     *
+     *       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.
      *
@@ -55,13 +155,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;
@@ -78,38 +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}|{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}}
+     * @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;
@@ -144,7 +230,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 +241,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.
@@ -175,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.
@@ -227,14 +306,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 +322,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;
@@ -289,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.
@@ -365,6 +448,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}
@@ -388,11 +493,9 @@ 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): any;
-    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;
     /**
      * @return {{expr: Expr, steps: number}}
@@ -402,11 +505,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;
+    final: boolean;
     diff(other: any, swap?: boolean): string;
     _braced(first: any): boolean;
     _format(options: any, nargs: any): string;
@@ -436,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.
      */
@@ -445,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.
@@ -465,12 +569,11 @@ export class Lambda extends Expr {
     arg: FreeVar;
     impl: Expr;
     arity: number;
-    _infer(options: any, preArgs?: any[], steps?: number): any;
     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;
@@ -490,18 +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;
-    arity: any;
-    note: any;
-    _rski(options: any): Expr | this;
 }
 export class Alias extends Named {
     /**
@@ -518,60 +617,60 @@ 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;
-    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): any;
-    /**
-     *
-     * @return {{expr: Expr, steps: number}}
-     */
-    step(): {
-        expr: Expr;
-        steps: number;
-    };
     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);
-    n: any;
+    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: {
     [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 {};