@dallaylaen/ski-interpreter 2.0.0 → 2.2.0

package/types/{lib → src}/expr.d.ts

@@ -1,3 +1,7 @@
+export type ActionWrapper<T> = T | {
+    value: T | null;
+    action: string;
+} | null;
 export type Partial = Expr | ((arg0: Expr) => Partial);
 /**
  * @typedef {Expr | function(Expr): Partial} Partial
@@ -11,7 +15,7 @@ export class Expr {
      */
     apply(...args: Expr): Expr;
     /**
-     * expand all terms but don't perform any calculations
+     * @desc Replace all aliases in the expression with their definitions, recursively.
      * @return {Expr}
      */
     expand(): Expr;
@@ -36,7 +40,28 @@ export class Expr {
      */
     any(predicate: (e: Expr) => boolean): boolean;
     /**
-     * @desc rought estimate of the complexity of the term
+     * @desc Fold the expression into a single value by recursively applying combine() to its subterms.
+     *       Nodes are traversed in leftmost-outermost order, i.e. the same order as reduction steps are taken.
+     *
+     * null or undefined return value from combine() means "keep current value and descend further".
+     *
+     * SKI.control provides primitives to control the folding flow:
+     *  - SKI.control.prune(value) means "use value and don't descend further into this branch";
+     *  - SKI.control.stop(value) means "stop folding immediately and return value".
+     *  - SKI.control.descend(value) is the default behavior, meaning "use value and descend further".
+     *
+     * This method is experimental and may change in the future.
+     *
+     * @experimental
+     * @template T
+     * @param {T} initial
+     * @param {(acc: T, expr: Expr) => ActionWrapper<T>} combine
+     * @returns {T}
+     */
+    fold<T>(initial: T, combine: (acc: T, expr: Expr) => ActionWrapper<T>): T;
+    _fold(initial: any, combine: any): any;
+    /**
+     * @desc rough estimate of the complexity of the term
      * @return {number}
      */
     weight(): number;
@@ -52,7 +77,7 @@ export class Expr {
      *
      *       Use toLambda() if you want to get a lambda term in any case.
      *
-     * @param {{max: number?, maxArgs: number?}} options
+     * @param {{max?: number, maxArgs?: number}} options
      * @return {{
      *    normal: boolean,
      *    steps: number,
@@ -66,8 +91,8 @@ export class Expr {
      * }}
      */
     infer(options?: {
-        max: number | null;
-        maxArgs: number | null;
+        max?: number;
+        maxArgs?: number;
     }): {
         normal: boolean;
         steps: number;
@@ -79,9 +104,27 @@ export class Expr {
         skip?: Set<number>;
         dup?: Set<number>;
     };
-    _infer(options: any, preArgs?: any[], steps?: number): any;
-    _aslist(): this[];
-    _firstVar(): boolean;
+    /**
+     *
+     * @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}}
+     * @private
+     */
+    private _infer;
+    /**
+     * @desc Expand an expression into a list of terms
+     * that give the initial expression when applied from left to right:
+     * ((a, b), (c, d)) => [a, b, (c, d)]
+     *
+     * This can be thought of as an opposite of apply:
+     * fun.apply(...arg).unroll() is exactly [fun, ...args]
+     * (even if ...arg is in fact empty).
+     *
+     * @returns {Expr[]}
+     */
+    unroll(): Expr[];
     /**
      * @desc Returns a series of lambda terms equivalent to the given expression,
      *       up to the provided computation steps limit,
@@ -122,17 +165,23 @@ export class Expr {
      *
      *     See also Expr.walk() and Expr.toLambda().
      *
-     * @param {{max: number?}} options
+     * @param {{max?: number}} [options]
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
     toSKI(options?: {
-        max: number | null;
+        max?: number;
     }): IterableIterator<{
         final: boolean;
         expr: Expr;
         steps: number;
     }>;
-    _rski(options: any): this;
+    /**
+     * @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.
@@ -256,7 +305,13 @@ export class Expr {
      * @return {boolean}
      */
     _braced(first?: boolean): boolean;
-    _unspaced(arg: any): boolean;
+    /**
+     * @desc Whether the expression can be printed without a space when followed by arg.
+     * @param {Expr} arg
+     * @returns {boolean}
+     * @private
+     */
+    private _unspaced;
     /**
      * @desc    Stringify the expression with fancy formatting options.
      *          Said options mostly include wrappers around various constructs in form of ['(', ')'],
@@ -302,31 +357,43 @@ export class Expr {
             [x: string]: Expr;
         };
     }): string;
-    _format(options: any, nargs: any): void;
-    _declare(output: any, inventory: any, seen: any): void;
+    /**
+     * @desc Internal method for format(), which performs the actual formatting.
+     * @param {Object} options
+     * @param {number} nargs
+     * @returns {string}
+     * @private
+     */
+    private _format;
+    /**
+     * @desc Convert the expression to a JSON-serializable format.
+     * @returns {string}
+     */
+    toJSON(): string;
 }
 export namespace Expr {
-    export { declare };
     export { native };
+    export { control };
+    export namespace extras {
+        export { toposort };
+    }
 }
 export class App extends Expr {
     /**
      * @desc Application of fun() to args.
-     * Never ever use new App(fun, ...args) directly, use fun.apply(...args) instead.
+     * Never ever use new App(fun, arg) directly, use fun.apply(...args) instead.
      * @param {Expr} fun
-     * @param {Expr} args
+     * @param {Expr} arg
      */
-    constructor(fun: Expr, ...args: Expr);
-    arg: any;
-    fun: any;
+    constructor(fun: Expr, arg: Expr);
+    arg: Expr;
+    fun: Expr;
     final: boolean;
-    arity: any;
-    weight(): any;
-    _firstVar(): any;
-    expand(): any;
-    traverse(change: any): any;
+    arity: number;
+    _infer(options: any, preArgs?: any[], steps?: number): any;
+    traverse(change: any): Expr;
     any(predicate: any): any;
-    subst(search: any, replace: any): any;
+    subst(search: any, replace: any): Expr;
     /**
      * @return {{expr: Expr, steps: number}}
      */
@@ -334,13 +401,27 @@ export class App extends Expr {
         expr: Expr;
         steps: number;
     };
-    invoke(arg: any): any;
-    split(): any[];
-    _aslist(): any[];
+    invoke(arg: any): Partial;
+    /**
+     * @desc Convert the expression to SKI combinatory logic
+     * @return {Expr}
+     */
+    _rski(options: any): Expr;
     diff(other: any, swap?: boolean): string;
     _braced(first: any): boolean;
+    _format(options: any, nargs: any): string;
+    _unspaced(arg: any): boolean;
+}
+export class Named extends Expr {
+    /**
+     * @desc An abstract class representing a term named 'name'.
+     *
+     * @param {String} name
+     */
+    constructor(name: string);
+    name: string;
+    _unspaced(arg: any): boolean;
     _format(options: any, nargs: any): any;
-    _unspaced(arg: any): any;
 }
 export class FreeVar extends Named {
     /**
@@ -384,14 +465,14 @@ 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;
     any(predicate: any): any;
     subst(search: any, replace: any): Lambda;
-    expand(): Lambda;
     _rski(options: any): any;
     diff(other: any, swap?: boolean): string;
-    _format(options: any, nargs: any): any;
+    _format(options: any, nargs: any): string;
     _braced(first: any): boolean;
 }
 export class Native extends Named {
@@ -420,7 +501,7 @@ export class Native extends Named {
     invoke: Partial;
     arity: any;
     note: any;
-    _rski(options: any): any;
+    _rski(options: any): Expr | this;
 }
 export class Alias extends Named {
     /**
@@ -456,6 +537,7 @@ export class Alias extends Named {
     traverse(change: any): any;
     any(predicate: any): any;
     subst(search: any, replace: any): any;
+    _infer(options: any, preArgs?: any[], steps?: number): any;
     /**
      *
      * @return {{expr: Expr, steps: number}}
@@ -479,26 +561,42 @@ export class Church extends Native {
     arity: number;
     diff(other: any, swap?: boolean): string;
 }
-/**
- *
- * @param {Expr[]} inventory
- * @return {string[]}
- */
-declare function declare(inventory: Expr[]): string[];
 /**
  * @type {{[key: string]: Native}}
  */
 declare const native: {
     [key: string]: Native;
 };
-declare class Named extends Expr {
-    /**
-     * @desc An abstract class representing a term named 'name'.
-     *
-     * @param {String} name
-     */
-    constructor(name: string);
-    name: string;
-    _format(options: any, nargs: any): any;
+declare namespace control {
+    let descend: (arg0: any) => any;
+    let prune: (arg0: any) => any;
+    let stop: (arg0: any) => any;
 }
+/**
+ * @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.
+ *        If env is omitted, it will be implied from the list.
+ *        If list is omitted, it will default to values of env.
+ *        If just one term is given instead of a list, it will be coerced into a list.
+ *
+ *        No terms outside env + list may ever appear in the result.
+ *
+ *        The terms in env must be named and their names must match their keys.
+ *
+ * @param {Expr|Expr[]} list
+ * @param {{[s:string]: Named}} env
+ * @returns {{list: Expr[], env: {[s:string]: Named}}}
+ *
+ * @example
+ *    const expr = ski.parse(src);
+ *    toposort([expr], ski.getTerms()); // returns all terms appearing in Expr in correct order
+ */
+declare function toposort(list: Expr | Expr[], env: {
+    [s: string]: Named;
+}): {
+    list: Expr[];
+    env: {
+        [s: string]: Named;
+    };
+};
 export {};

package/types/src/extras.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @desc  Extra utilities that do not belong in the core.
+ */
+/**
+ * @experimental
+ * @desc  Look for an expression that matches the predicate,
+ *        starting with the seed and applying the terms to one another.
+ *
+ *        A predicate returning 0 (or nothing) means "keep looking",
+ *        a positive number stands for "found",
+ *        and a negative means "discard this term from further applications".
+ *
+ *        The order of search is from shortest to longest expressions.
+ *
+ * @param {Expr[]} seed
+ * @param {object} options
+ * @param {number} [options.depth] - maximum generation to search for
+ * @param {number} [options.tries] - maximum number of tries before giving up
+ * @param {boolean} [options.infer] - whether to call infer(), default true.
+ * @param {number} [options.maxArgs] - arguments in infer()
+ * @param {number} [options.max] - step limit in infer()
+ * @param {boolean} [options.noskip] - prevents skipping equivalent terms. Always true if infer is false.
+ * @param {boolean} [retain] - if true. also add the whole cache to returned value
+ * @param {({gen: number, total: number, probed: number, step: boolean}) => void} [options.progress]
+ * @param {number} [options.progressInterval] - minimum number of tries between calls to options.progress, default 1000.
+ * @param {(e: Expr, props: {}) => number?} predicate
+ * @return {{expr?: Expr, total: number, probed: number, gen: number, cache?: Expr[][]}}
+ */
+export function search(seed: Expr[], options: {
+    depth?: number;
+    tries?: number;
+    infer?: boolean;
+    maxArgs?: number;
+    max?: number;
+    noskip?: boolean;
+}, predicate: (e: Expr, props: {}) => number | null): {
+    expr?: Expr;
+    total: number;
+    probed: number;
+    gen: number;
+    cache?: Expr[][];
+};
+/**
+ * @desc Recursively replace all instances of Expr in a data structure with
+ *       respective string representation using the format() options.
+ *       Objects of other types and primitive values are eft as is.
+ *
+ *       May be useful for debugging or diagnostic output.
+ *
+ * @experimental
+ *
+ * @param {any} obj
+ * @param {object} [options] - see Expr.format()
+ * @returns {any}
+ */
+export function deepFormat(obj: any, options?: object): any;
+export function declare(expr: any, env: any): string;
+import { Expr } from "./expr";

package/types/src/internal.d.ts

@@ -0,0 +1,52 @@
+export class Tokenizer {
+    /**
+     * @desc Create a tokenizer that splits strings into tokens according to the given terms.
+     * The terms are interpreted as regular expressions, and are sorted by length
+     * to ensure that longer matches are preferred over shorter ones.
+     * @param {...string|RegExp} terms
+     */
+    constructor(...terms: (string | RegExp)[]);
+    rex: RegExp;
+    /**
+     * @desc Split the given string into tokens according to the terms specified in the constructor.
+     * @param {string} str
+     * @return {string[]}
+     */
+    split(str: string): string[];
+}
+/**
+ * @desc Add ot remove tokens from a set according to a spec string.
+ * The spec string is a sequence of tokens, with each group optionally prefixed
+ * by one of the operators '=', '+', or '-'.
+ * The '=' operator resets the set to contain only the following token(s).
+ * @param {Set<string>} set
+ * @param {string} [spec]
+ * @returns {Set<string>}
+ */
+export function restrict(set: Set<string>, spec?: string): Set<string>;
+/**
+ * @private
+ * @template T
+ * @param {T|ActionWrapper<T>} value
+ * @returns {[T?, string|undefined]}
+ */
+export function unwrap<T>(value: T | ActionWrapper<T>): [T?, string | undefined];
+/**
+ *
+ * @private
+ * @template T
+ * @param {string} action
+ * @returns {function(T): ActionWrapper<T>}
+ */
+export function prepareWrapper<T>(action: string): (arg0: T) => ActionWrapper<T>;
+declare class ActionWrapper {
+    /**
+     * @template T
+     * @param {T} value
+     * @param {string} action
+     */
+    constructor(value: T, action: string);
+    value: T;
+    action: string;
+}
+export {};

package/types/{lib → src}/parser.d.ts

@@ -86,7 +86,8 @@ export class SKI {
         [key: string]: typeof classes.Native | typeof classes.Alias;
     };
     /**
-     * Export term declarations for use in bulkAdd().
+     * @desc Export term declarations for use in bulkAdd().
+     * Currently only Alias terms are serialized.
      * @returns {string[]}
      */
     declare(): string[];
@@ -143,7 +144,9 @@ export class SKI {
     };
 }
 export namespace SKI {
-    export { classes };
+    /**
+     *  Public static shortcuts to common functions (see also ./extras.js)
+     */
     /**
      * @desc Create a proxy object that generates variables on demand,
      *       with names corresponding to the property accessed.
@@ -167,12 +170,16 @@ export namespace SKI {
      * @return {Church}
      */
     export function church(n: number): typeof import("./expr").Church;
+    export { classes };
     export { native };
-    export { declare };
+    export let control: {
+        descend: (arg0: any) => any;
+        prune: (arg0: any) => any;
+        stop: (arg0: any) => any;
+    };
 }
 import classes = require("./expr");
 declare const native: {
     [key: string]: classes.Native;
 };
-declare const declare: (inventory: Expr[]) => string[];
 export {};

package/types/{lib → src}/quest.d.ts

@@ -18,6 +18,13 @@ export type Capability = {
     duplicate: boolean | null;
     arity: number | null;
 };
+export type InputSpec = string | {
+    name: string;
+    fancy?: string;
+    allow?: string;
+    numbers?: boolean;
+    lambdas?: boolean;
+};
 export type QuestResult = {
     pass: boolean;
     details: CaseResult[];
@@ -58,6 +65,9 @@ export type QuestResult = {
  *   | [{caps: Capability, max: number?}, string]
  * } TestCase
  */
+/**
+ * @typedef {string | {name: string, fancy?: string, allow?: string, numbers?: boolean, lambdas?: boolean}} InputSpec
+ */
 /**
  * @typedef {{
  *   pass: boolean,
@@ -73,48 +83,55 @@ export class Quest {
     /**
      * @description A combinator problem with a set of test cases for the proposed solution.
      * @param {{
-     *    title: string?,
-     *    descr: string?,
-     *    subst: string?,
-     *    allow: string?,
-     *    numbers: boolean?,
-     *    vars: string[]?,
-     *    engine: SKI?,
-     *    engineFull: SKI?,
+     *    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
+     *
+     * @example const quest = new Quest({
+     *    input: 'identity',
+     *    cases: [
+     *      ['identity x', 'x'],
+     *    ],
+     *    allow: 'SK',
+     *    intro: 'Find a combinator that behaves like the identity function.',
+     * });
+     * quest.check('S K K'); // { pass: true, details: [...], ... }
+     * quest.check('K S');   // { pass: false, details: [...], ... }
+     * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
+     *                       //     despite having the same name.
+     * quest.check('I');     // fail! I not in the allowed list.
      */
-    constructor(options?: {
-        title: string | null;
-        descr: string | null;
-        subst: string | null;
-        allow: string | null;
-        numbers: boolean | null;
-        vars: string[] | null;
-        engine: SKI | null;
-        engineFull: SKI | null;
-        cases: TestCase[];
-    });
-    engine: SKI;
-    engineFull: SKI;
+    constructor(options?: {});
+    engine: any;
+    engineFull: any;
     restrict: {
-        allow: string;
-        numbers: boolean;
+        allow: any;
+        numbers: any;
         lambdas: any;
     };
-    vars: {};
-    subst: string[] | (string & any[]);
+    env: {};
     input: any[];
-    varsFull: {};
+    envFull: {};
     cases: any[];
-    title: string;
-    descr: string;
-    meta: {
-        title: string | null;
-        descr: string | null;
-    };
+    name: any;
+    intro: any;
+    id: any;
+    meta: {};
     /**
-     *   Display allowed terms based on what engine thinks of this.vars + this.restrict.allow
+     *   Display allowed terms based on what engine thinks of this.env + this.restrict.allow
      *   @return {string}
      */
     allowed(): string;
@@ -153,21 +170,21 @@ declare class Case {
      * @param {{
      *   max?: number,
      *   note?: string,
-     *   vars?: {[key:string]: Expr},
+     *   env?: {[key:string]: Expr},
      *   engine: SKI
      * }} options
      */
     constructor(input: typeof import("./expr").FreeVar[], options: {
         max?: number;
         note?: string;
-        vars?: {
+        env?: {
             [key: string]: typeof import("./expr").Expr;
         };
         engine: SKI;
     });
     max: number;
     note: string;
-    vars: {
+    env: {
         [key: string]: typeof import("./expr").Expr;
     };
     input: typeof import("./expr").FreeVar[];
@@ -184,11 +201,11 @@ declare class Subst {
     /**
      * @descr A placeholder object with exactly n free variables to be substituted later.
      * @param {Expr} expr
-     * @param {FreeVar[]} vars
+     * @param {FreeVar[]} env
      */
-    constructor(expr: typeof import("./expr").Expr, vars: typeof import("./expr").FreeVar[]);
+    constructor(expr: typeof import("./expr").Expr, env: typeof import("./expr").FreeVar[]);
     expr: typeof import("./expr").Expr;
-    vars: typeof import("./expr").FreeVar[];
+    env: typeof import("./expr").FreeVar[];
     apply(list: any): typeof import("./expr").Expr;
 }
 export {};

package/index.js

@@ -1,8 +0,0 @@
-const ski = require('./lib/parser');
-const quest = require('./lib/quest');
-
-module.exports = { ...ski, ...quest };
-if (typeof window !== 'undefined') {
-  window.SKI = ski.SKI;
-  window.SKI.Quest = quest.Quest;
-}