@dallaylaen/ski-interpreter 2.3.2 → 2.4.0

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

@@ -1,3 +1,5 @@
+import { Expr, Named, FormatOptions, TermInfo } from './expr';
+import { toposort } from './toposort';
 /**
  * @desc  Extra utilities that do not belong in the core.
  */
@@ -26,20 +28,31 @@
  * @param {(e: Expr, props: {}) => number?} predicate
  * @return {{expr?: Expr, total: number, probed: number, gen: number, cache?: Expr[][]}}
  */
-export function search(seed: Expr[], options: {
+type SearchOptions = {
     depth?: number;
     tries?: number;
     infer?: boolean;
     maxArgs?: number;
     max?: number;
     noskip?: boolean;
-}, predicate: (e: Expr, props: {}) => number | null): {
+    retain?: boolean;
+    progress?: (info: {
+        gen: number;
+        total: number;
+        probed: number;
+        step: boolean;
+    }) => void;
+    progressInterval?: number;
+};
+type SearchCallback = (e: Expr, props: TermInfo) => (number | undefined);
+type SearchResult = {
     expr?: Expr;
     total: number;
     probed: number;
     gen: number;
     cache?: Expr[][];
 };
+declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): SearchResult;
 /**
  * @desc Recursively replace all instances of Expr in a data structure with
  *       respective string representation using the format() options.
@@ -48,12 +61,8 @@ export function search(seed: Expr[], options: {
  *       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;
+declare function deepFormat(obj: any, options?: FormatOptions): any;
 /**
  * @desc  Given an expression and a hash of named terms,
  *        return a semicolon-separated string that declares said expression
@@ -68,21 +77,13 @@ export function deepFormat(obj: any, options?: object): any;
  * @param {{[s: string]: Named}} [env]
  * @returns {string}
  */
-export function declare(expr: Expr, env?: {
+declare function declare(expr: Expr, env?: {
     [s: string]: Named;
 }): string;
-/**
- * @experimental
- * @desc  Fold an application tree bottom to top.
- *        For each subtree, the function is given the term in the root position and
- *        a list of the results of folding its arguments.
- *
- *        E,g, fold('x y (z t)', f) results in f(x, [f(y, []), f(z, [f(t, [])])])
- *
- * @template T
- * @param {Expr} expr
- * @param {(head: Expr, tail: T[]) => T} fun
- * @return {T}
- */
-export function foldr<T>(expr: Expr, fun: (head: Expr, tail: T[]) => T): T;
-import { Expr } from "./expr";
+export declare const extras: {
+    search: typeof search;
+    deepFormat: typeof deepFormat;
+    declare: typeof declare;
+    toposort: typeof toposort;
+};
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,68 @@
+import { FreeVar, Church } from './expr';
+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 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 classes: {
+        Expr: typeof import("./expr").Expr;
+        App: typeof import("./expr").App;
+        Named: typeof import("./expr").Named;
+        FreeVar: typeof FreeVar;
+        Native: typeof import("./expr").Native;
+        Lambda: typeof import("./expr").Lambda;
+        Church: typeof Church;
+        Alias: typeof import("./expr").Alias;
+    };
+    static B: import("./expr").Native;
+    static C: import("./expr").Native;
+    static I: import("./expr").Native;
+    static K: import("./expr").Native;
+    static S: import("./expr").Native;
+    static W: import("./expr").Native;
+    static vars(scope?: object): {
+        [key: string]: FreeVar;
+    };
+    static church(n: number): Church;
+    static extras: {
+        search: (seed: import("./expr").Expr[], options: {
+            depth?: number;
+            tries?: number;
+            infer?: boolean;
+            maxArgs?: number;
+            max?: number;
+            noskip?: boolean;
+            retain?: boolean;
+            progress?: (info: {
+                gen: number;
+                total: number;
+                probed: number;
+                step: boolean;
+            }) => void;
+            progressInterval?: number;
+        }, predicate: (e: import("./expr").Expr, props: import("./expr").TermInfo) => (number | undefined)) => {
+            expr?: import("./expr").Expr;
+            total: number;
+            probed: number;
+            gen: number;
+            cache?: import("./expr").Expr[][];
+        };
+        deepFormat: (obj: any, options?: import("./expr").FormatOptions) => any;
+        declare: (expr: import("./expr").Expr, env?: {
+            [s: string]: import("./expr").Named;
+        }) => string;
+        toposort: typeof toposort;
+    };
+    static Quest: typeof Quest;
+}
+declare global {
+    interface Window {
+        SKI: typeof SKI;
+    }
+}

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

@@ -1,12 +1,15 @@
-export class Tokenizer {
+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.
      * 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;
+    constructor(...terms: (string | RegExp)[]);
     /**
      * @desc Split the given string into tokens according to the terms specified in the constructor.
      * @param {string} str
@@ -23,14 +26,33 @@ export class Tokenizer {
  * @param {string} [spec]
  * @returns {Set<string>}
  */
-export function restrict(set: Set<string>, spec?: string): Set<string>;
+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;
+export declare class TraverseControl<T> {
+    /**
+     * @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 {function(T): TraverseControl<T>} decoration
+     */
+    value: T;
+    decoration: TraverseDecorator<T>;
+    constructor(value: T, decoration: TraverseDecorator<T>);
+}
 /**
  * @private
  * @template T
  * @param {T|TraverseControl<T>|null} value
  * @returns {[T?, function|undefined]}
  */
-export function unwrap<T>(value: T | TraverseControl<T> | null): [T?, Function | undefined];
+export declare function unwrap<T>(value: TraverseValue<T>): [T?, TraverseDecorator<T>?];
 /**
  * @desc Prepare a self-referencing wrapper function for use as a fold/traverse control decorator.
  *
@@ -44,22 +66,4 @@ export function unwrap<T>(value: T | TraverseControl<T> | null): [T?, Function |
  * @param {string} [label]
  * @returns {function(T): TraverseControl<T>}
  */
-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 {function(T): TraverseControl<T>} decoration
-     */
-    constructor(value: T, decoration: (arg0: T) => TraverseControl<T>);
-    value: T;
-    decoration: (arg0: T) => TraverseControl<T>;
-}
-export {};
+export declare function prepareWrapper(label: string): <T>(value: T) => TraverseControl<T>;

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

@@ -1,4 +1,29 @@
-export class SKI {
+import { Expr, Alias, Native, Invocation } from './expr';
+export type ParserOptions = {
+    allow?: string;
+    numbers?: boolean;
+    lambdas?: boolean;
+    terms?: {
+        [key: string]: Expr | string;
+    } | string[];
+    annotate?: boolean;
+};
+export type ParseOptions = {
+    env?: {
+        [key: string]: Expr;
+    };
+    scope?: object;
+    numbers?: boolean;
+    lambdas?: boolean;
+    allow?: string;
+};
+export type AddOptions = {
+    note?: string;
+    canonize?: boolean;
+    fancy?: string;
+    arity?: number;
+};
+export declare class Parser {
     /**
      *
      * @param {{
@@ -9,23 +34,14 @@ export class SKI {
      *    annotate?: boolean,
      * }} [options]
      */
-    constructor(options?: {
-        allow?: string;
-        numbers?: boolean;
-        lambdas?: boolean;
-        terms?: {
-            [key: string]: typeof classes.Expr | string;
-        } | string[];
-        annotate?: boolean;
-    });
     annotate: boolean;
     known: {
-        [key: string]: classes.Native;
+        [name: string]: Expr;
     };
+    allow: Set<string>;
     hasNumbers: boolean;
     hasLambdas: boolean;
-    /** @type {Set<string>} */
-    allow: Set<string>;
+    constructor(options?: ParserOptions);
     /**
      * @desc Declare a new term
      * If the first argument is an Alias, it is added as is.
@@ -49,7 +65,7 @@ export class SKI {
      * @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), options?: object | string): SKI;
+    add(term: Alias | string, impl?: Expr | string | ((arg: Expr) => Invocation), options?: AddOptions | string): this;
     /**
      * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
      * @param {Alias|string} term
@@ -57,7 +73,7 @@ export class SKI {
      * @returns {Native|Alias}
      * @private
      */
-    private _named;
+    _named(term: Alias | string, impl?: Expr | string | ((arg: Expr) => Invocation)): Native | Alias;
     /**
      * @desc Declare a new term if it is not known, otherwise just allow it.
      *       Currently only used by quests.
@@ -68,7 +84,7 @@ export class SKI {
      * @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;
+    maybeAdd(name: string, impl: Expr | string | ((arg: Expr) => Invocation)): this;
     /**
      * @desc Declare and remove multiple terms at once
      *       term=impl adds term
@@ -76,7 +92,7 @@ export class SKI {
      * @param {string[]} list
      * @return {SKI} chainable
      */
-    bulkAdd(list: string[]): SKI;
+    bulkAdd(list: string[]): this;
     /**
      * Restrict the interpreter to given terms. Terms prepended with '+' will be added
      * and terms preceeded with '-' will be removed.
@@ -87,7 +103,7 @@ export class SKI {
      * @param {string} spec
      * @return {SKI} chainable
      */
-    restrict(spec: string): SKI;
+    restrict(spec: string): this;
     /**
      *
      * @param {string} spec
@@ -99,13 +115,13 @@ export class SKI {
      * @param {String} name
      * @return {SKI}
      */
-    remove(name: string): SKI;
+    remove(name: string): this;
     /**
      *
      * @return {{[key:string]: Native|Alias}}
      */
     getTerms(): {
-        [key: string]: typeof classes.Native | typeof classes.Alias;
+        [key: string]: Expr;
     };
     /**
      * @desc Export term declarations for use in bulkAdd().
@@ -124,15 +140,7 @@ export class SKI {
      * @param {string} [options.allow]
      * @return {Expr}
      */
-    parse<T_1>(source: string, options?: {
-        env?: {
-            [keys: string]: typeof classes.Expr;
-        };
-        scope?: T_1;
-        numbers?: boolean;
-        lambdas?: boolean;
-        allow?: string;
-    }): typeof classes.Expr;
+    parse(source: string, options?: ParseOptions): Expr;
     /**
      * @desc Parse a single line of source code, without splitting it into declarations.
      *       Internal, always use parse() instead.
@@ -147,17 +155,9 @@ export class SKI {
      * @param {string} [options.allow]
      * @return {Expr} parsed expression
      */
-    parseLine<T_1>(source: string, env?: {
-        [keys: string]: typeof classes.Expr;
-    }, options?: {
-        env?: {
-            [keys: string]: typeof classes.Expr;
-        };
-        scope?: T_1;
-        numbers?: boolean;
-        lambdas?: boolean;
-        allow?: string;
-    }): typeof classes.Expr;
+    parseLine(source: string, env?: {
+        [key: string]: Expr;
+    }, options?: ParseOptions): Expr;
     toJSON(): {
         version: string;
         allow: string;
@@ -167,46 +167,3 @@ export class SKI {
         terms: string[];
     };
 }
-export namespace SKI {
-    /**
-     *  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.
-     *       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)
-     *
-     * @template T
-     * @param {T} [scope] - optional context to bind the generated variables to
-     * @return {{[key: string]: FreeVar}}
-     */
-    export function vars<T_1>(scope?: T_1): {
-        [key: string]: typeof import("./expr").FreeVar;
-    };
-    /**
-     * Convert a number to Church encoding
-     * @param {number} n
-     * @return {Church}
-     */
-    export function church(n: number): typeof import("./expr").Church;
-    export { classes };
-    export { native };
-    export let control: {
-        descend: (arg0: T) => TraverseControl<T>;
-        prune: (arg0: T) => TraverseControl<T>;
-        redo: (arg0: T) => TraverseControl<T>;
-        stop: (arg0: T) => TraverseControl<T>;
-    };
-}
-import classes = require("./expr");
-declare const native: {
-    [key: string]: classes.Native;
-};
-export {};

package/lib/types/quest.d.ts

@@ -0,0 +1,232 @@
+import { Parser } from './parser';
+import { Expr, FreeVar, Alias } from './expr';
+export type CaseResult = {
+    pass: boolean;
+    reason?: string;
+    steps: number;
+    start: Expr;
+    found: Expr;
+    expected?: Expr;
+    note?: string;
+    args: Expr[];
+    case: Case;
+};
+export type Capability = {
+    linear?: boolean;
+    affine?: boolean;
+    normal?: boolean;
+    proper?: boolean;
+    discard?: boolean;
+    duplicate?: boolean;
+    arity?: number;
+};
+export type TestCase = [
+    string,
+    string
+] | [{
+    max?: number;
+}, string, string] | [{
+    caps: Capability;
+    max?: number;
+}, string];
+export type InputSpec = {
+    name: string;
+    fancy?: string;
+    allow?: string;
+    numbers?: boolean;
+    lambdas?: boolean;
+};
+export type QuestResult = {
+    pass: boolean;
+    details: CaseResult[];
+    expr?: Expr;
+    input: Expr[] | string[];
+    exception?: Error;
+    steps: number;
+    weight?: number;
+};
+type QuestMeta = {
+    [key: string]: any;
+};
+export type QuestSpec = {
+    input: string | InputSpec | (string | InputSpec)[];
+    cases: TestCase[];
+    allow?: string;
+    numbers?: boolean;
+    lambdas?: boolean;
+    env?: string[];
+    engine?: Parser;
+    engineFull?: Parser;
+    id?: string | number;
+    name?: string;
+    intro?: string | string[];
+} & QuestMeta;
+export type SelfCheck = {
+    accepted?: string[][];
+    rejected?: string[][];
+};
+type AddCaseOptions = {
+    engine?: Parser;
+    env?: {
+        [key: string]: Expr;
+    };
+    max?: number;
+    note?: string;
+    caps?: Capability;
+};
+export declare class Quest {
+    /**
+     * @description A combinator problem with a set of test cases for the proposed solution.
+     * @param {QuestSpec} 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.
+     */
+    input: (InputSpec & {
+        placeholder: FreeVar;
+    })[];
+    cases: Case[];
+    engineFull: Parser;
+    engine: Parser;
+    restrict: {
+        allow?: string;
+        numbers?: boolean;
+        lambdas?: boolean;
+    };
+    env: {
+        [key: string]: Expr;
+    };
+    envFull: {
+        [key: string]: Expr;
+    };
+    id?: string | number;
+    name?: string;
+    intro?: string;
+    meta?: QuestMeta;
+    constructor(options: QuestSpec);
+    /**
+     *   Display allowed terms based on what engine thinks of this.env + this.restrict.allow
+     *   @return {string}
+     */
+    allowed(): string;
+    addInput(term: string | InputSpec): void;
+    /**
+     *
+     * @param {{} | string} opt
+     * @param {string} terms
+     * @return {Quest}
+     */
+    add(opt: AddCaseOptions | string, ...terms: string[]): this;
+    /**
+     * @description Statefully parse a list of strings into expressions or fancy aliases thereof.
+     * @param {string[]} input
+     * @return {{terms: Expr[], weight: number}}
+     */
+    prepare(...input: string[]): {
+        prepared: (FreeVar | Alias)[];
+        weight: number;
+    };
+    /**
+     *
+     * @param {string} input
+     * @return {QuestResult}
+     */
+    check(...input: string[]): QuestResult;
+    verify(options: {
+        solutions?: SelfCheck | {
+            [key: string | number]: SelfCheck;
+        };
+        seen?: Set<string | number>;
+        date?: boolean;
+    }): {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * @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 | number]: SelfCheck;
+    }): {
+        shouldPass: {
+            input: string[];
+            result: QuestResult;
+        }[];
+        shouldFail: {
+            input: string[];
+            result: QuestResult;
+        }[];
+    } | null;
+    verifyMeta(options?: {
+        date?: boolean;
+    }): {
+        [key: string]: unknown;
+    };
+    /**
+       *
+       * @return {TestCase[]}
+       */
+    show(): Case[];
+    static Group: new (options: {
+        name?: string;
+        intro?: string | string[];
+        id?: string | number;
+        content?: (Quest | QuestSpec)[];
+    }) => {
+        verify: (options: {
+            seen?: Set<string | number>;
+            date?: boolean;
+        }) => {
+            [key: string]: unknown;
+        };
+    };
+    static Case: new (input: FreeVar[], options: AddCaseOptions) => Case;
+}
+declare class Case {
+    /**
+     * @param {FreeVar[]} input
+     * @param {{
+     *   max?: number,
+     *   note?: string,
+     *   env?: {[key:string]: Expr},
+     *   engine: Parser
+     * }} options
+     */
+    max: number;
+    note: string;
+    env: {
+        [key: string]: Expr;
+    };
+    input: FreeVar[];
+    engine: Parser;
+    constructor(input: FreeVar[], options: AddCaseOptions);
+    parse(src: string): Subst;
+    /**
+     * @param {Expr} expr
+     * @return {CaseResult}
+     */
+    check(..._expr: Expr[]): CaseResult;
+}
+declare class Subst {
+    /**
+     * @descr A placeholder object with exactly n free variables to be substituted later.
+     * @param {Expr} expr
+     * @param {FreeVar[]} env
+     */
+    expr: Expr;
+    env: FreeVar[];
+    constructor(expr: Expr, env: FreeVar[]);
+    apply(list: Expr[]): Expr;
+}
+export {};

package/lib/types/toposort.d.ts

@@ -0,0 +1,30 @@
+import { Expr, Named } from './expr';
+/**
+ * @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
+ */
+type ToposortResult = {
+    list: Expr[];
+    env: {
+        [s: string]: Named;
+    };
+};
+export declare function toposort(list: Expr[] | Expr | undefined, env: {
+    [s: string]: Named;
+} | undefined): ToposortResult;
+export {};