@dallaylaen/ski-interpreter 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dallaylaen/ski-interpreter",
+  "version": "1.0.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",
+    "lambda calculus",
+    "functional programming",
+    "education",
+    "interpreter"
+  ],
+  "main": "index.js",
+  "types": "types/index.d.ts",
+  "bin": {
+    "ski": "bin/ski.js"
+  },
+  "scripts": {
+    "test": "nyc mocha"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "lib",
+    "types"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dallaylaen/ski-interpreter.git"
+  },
+  "author": "Konstantin Uvarin",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dallaylaen/ski-interpreter/issues"
+  },
+  "homepage": "https://dallaylaen.github.io/ski-interpreter/index.html",
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-align-assignments": "^1.1.2",
+    "eslint-plugin-import": "^2.29.1",
+    "typescript": "^5.8.2",
+    "mocha": "^10.2.0",
+    "nyc": "^15.1.0"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,7 @@
+declare const _exports: {
+    Quest: typeof quest.Quest;
+    SKI: typeof ski.SKI;
+};
+export = _exports;
+import quest = require("./lib/quest");
+import ski = require("./lib/parser");

package/types/lib/expr.d.ts

@@ -0,0 +1,344 @@
+export type AnyArity = (arg0: Expr) => Expr | AnyArity;
+export class Expr {
+    arity: number;
+    /**
+       * postprocess term after parsing. typically return self but may return other term or die
+       * @return {Expr}
+       */
+    postParse(): Expr;
+    /**
+       * @desc apply self to zero or more terms and return the resulting term,
+       * without performing any calculations whatsoever
+       * @param {Expr} args
+       * @return {Expr}
+       */
+    apply(...args: Expr): Expr;
+    /**
+       * expand all terms but don't perform any calculations
+       * @return {Expr}
+       */
+    expand(): Expr;
+    /**
+     * @desc return all free variables within the term
+     * @return {Set<FreeVar>}
+     */
+    freeVars(): Set<FreeVar>;
+    hasLambda(): any;
+    freeOnly(): boolean;
+    /**
+     * @desc return all terminal values within the term, that is, values not
+     * composed of other terms. For example, in S(KI)K, the terminals are S, K, I.
+     * @return {Map<Expr, number>}
+     */
+    getSymbols(): Map<Expr, number>;
+    /**
+     * @desc rought estimate of the complexity of the term
+     * @return {number}
+     */
+    weight(): number;
+    /**
+     *
+     * @param {{max: number?, maxArgs: number?, bestGuess?: Expr}} options
+     * @return {{
+     *    found: boolean,
+     *    proper: boolean,
+     *    arity: number?,
+     *    linear: boolean?,
+     *    canonical?: Expr,
+     *    steps: number?,
+     *    skip: Set<number>?
+     * }}
+     */
+    canonize(options?: {
+        max: number | null;
+        maxArgs: number | null;
+        bestGuess?: Expr;
+    }): {
+        found: boolean;
+        proper: boolean;
+        arity: number | null;
+        linear: boolean | null;
+        canonical?: Expr;
+        steps: number | null;
+        skip: Set<number> | null;
+    };
+    /**
+     * @desc Returns a series of lambda terms equivalent to the given expression,
+     *       up to the provided computation steps limit,
+     *       in decreasing weight order.
+     * @param {{
+     *   max: number?,
+     *   maxArgs: number?,
+     *   varGen: function(void): FreeVar?,
+     *   steps: number?,
+     *   html: boolean?,
+     *   latin: number?,
+     * }} options
+     * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
+     * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
+     */
+    lambdify(options?: {
+        max: number | null;
+        maxArgs: number | null;
+        varGen: (arg0: void) => FreeVar | null;
+        steps: number | null;
+        html: boolean | null;
+        latin: number | null;
+    }): IterableIterator<{
+        expr: Expr;
+        steps: number | null;
+        comment: string | null;
+    }>;
+    /**
+     * @desc same semantics as walk() but rewrite step by step instead of computing
+     * @param {{max: number?}} options
+     * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
+     */
+    rewriteSKI(options?: {
+        max: number | null;
+    }): IterableIterator<{
+        final: boolean;
+        expr: Expr;
+        steps: number;
+    }>;
+    /**
+     * @desc Rename free variables in the expression using the given sequence
+     *       This is for eye-candy only, as the interpreter knows darn well hot to distinguish vars,
+     *       regardless of names.
+     * @param {IterableIterator<string>} seq
+     * @return {Expr}
+     */
+    renameVars(seq: IterableIterator<string>): Expr;
+    _rski(options: any): this;
+    /**
+     * @desc Whether the term will reduce further if given more arguments.
+     *       In practice, equivalent to "starts with a FreeVar"
+     *       Used by canonize (duh...)
+     * @return {boolean}
+     */
+    wantsArgs(): boolean;
+    /**
+       * Apply self to list of given args.
+       * Normally, only native combinators know how to do it.
+       * @param {Expr[]} args
+       * @return {Expr|null}
+       */
+    reduce(args: Expr[]): Expr | null;
+    /**
+       * Replace all instances of free vars with corresponding values and return the resulting expression.
+       * return null if no changes could be made.
+       * @param {FreeVar} plug
+       * @param {Expr} value
+       * @return {Expr|null}
+       */
+    subst(plug: FreeVar, value: Expr): Expr | null;
+    /**
+       * @desc iterate one step of calculation in accordance with known rules.
+       * @return {{expr: Expr, steps: number, changed: boolean}}
+       */
+    step(): {
+        expr: Expr;
+        steps: number;
+        changed: boolean;
+    };
+    /**
+       * @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 {Expr} args
+       * @return {{expr: Expr, steps: number, final: boolean}}
+       */
+    run(opt?: {
+        max: number | null;
+        steps: number | null;
+        throw: boolean | null;
+    } | Expr, ...args: Expr): {
+        expr: Expr;
+        steps: number;
+        final: boolean;
+    };
+    /**
+       * Execute step() while possible, yielding a brief description of events after each step.
+       * Mnemonics: like run() but slower.
+       * @param {{max: number?}} options
+       * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
+       */
+    walk(options?: {
+        max: number | null;
+    }): IterableIterator<{
+        final: boolean;
+        expr: Expr;
+        steps: number;
+    }>;
+    /**
+       *
+       * @param {Expr} other
+       * @return {boolean}
+       */
+    equals(other: Expr): boolean;
+    contains(other: any): boolean;
+    expect(other: any): void;
+    /**
+     * @param {{terse: boolean?, html: boolean?}} [options]
+     * @return {string} string representation of the expression
+     */
+    toString(options?: {
+        terse: boolean | null;
+        html: boolean | null;
+    }): string;
+    /**
+     *
+     * @return {boolean}
+     */
+    needsParens(): boolean;
+    /**
+     *
+     * @return {string}
+     */
+    toJSON(): string;
+}
+export namespace Expr {
+    let lambdaPlaceholder: Native;
+}
+export class App extends Expr {
+    /**
+     * @desc Application of fun() to args.
+     * Never ever use new App(fun, ...args) directly, use fun.apply(...args) instead.
+     * @param {Expr} fun
+     * @param {Expr} args
+     */
+    constructor(fun: Expr, ...args: Expr);
+    fun: Expr;
+    args: Expr;
+    final: boolean;
+    weight(): Expr;
+    apply(...args: any[]): any;
+    canonize(options?: {}): {
+        found: boolean;
+        proper: boolean;
+        arity: number | null;
+        linear: boolean | null;
+        canonical?: Expr;
+        steps: number | null;
+        skip: Set<number> | null;
+    };
+    renameVars(seq: any): Expr;
+    subst(plug: any, value: any): Expr;
+    /**
+     * @return {{expr: Expr, steps: number}}
+     */
+    step(): {
+        expr: Expr;
+        steps: number;
+    };
+    split(): any[];
+    equals(other: any): boolean;
+    toString(opt?: {}): string;
+}
+export class FreeVar extends Named {
+    constructor(name: any);
+    id: number;
+    subst(plug: any, value: any): any;
+    toString(opt?: {}): string;
+}
+export class Lambda extends Expr {
+    /**
+       * @param {FreeVar|FreeVar[]} arg
+       * @param {Expr} impl
+       */
+    constructor(arg: FreeVar | FreeVar[], impl: Expr);
+    arg: FreeVar;
+    impl: Expr;
+    reduce(input: any): Expr;
+    subst(plug: any, value: any): Lambda;
+    expand(): Lambda;
+    renameVars(seq: any): Lambda;
+    _rski(options: any): any;
+    equals(other: any): boolean;
+    toString(opt?: {}): string;
+}
+/**
+ * @typedef {function(Expr): Expr | AnyArity} AnyArity
+ */
+export class Native extends Named {
+    /**
+     * @desc A term named 'name' that converts next 'arity' arguments into
+     *       an expression returned by 'impl' function
+     *       If an apply: Expr=>Expr|null function is given, it will be attempted upon application
+     *       before building an App object. This allows to plug in argument coercions,
+     *       e.g. instantly perform a numeric operation natively if the next term is a number.
+     * @param {String} name
+     * @param {AnyArity} impl
+     * @param {{note: string?, arity: number?, canonize: boolean?, apply: function(Expr):(Expr|null) }} [opt]
+     */
+    constructor(name: string, impl: AnyArity, opt?: {
+        note: string | null;
+        arity: number | null;
+        canonize: boolean | null;
+        apply: (arg0: Expr) => (Expr | null);
+    });
+    impl: AnyArity;
+    onApply: (arg0: Expr) => (Expr | null);
+    arity: any;
+    note: any;
+    apply(...args: any[]): Expr;
+    _rski(options: any): Expr | this;
+    reduce(args: any): any;
+}
+export class Alias extends Named {
+    /**
+     * @desc An existing expression under a different name.
+     * @param {String} name
+     * @param {Expr} impl
+     * @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;
+    });
+    impl: Expr;
+    note: string;
+    arity: any;
+    proper: any;
+    terminal: any;
+    canonical: any;
+    subst(plug: any, value: any): Expr;
+    /**
+     *
+     * @return {{expr: Expr, steps: number}}
+     */
+    step(): {
+        expr: Expr;
+        steps: number;
+    };
+    reduce(args: any): Expr;
+    equals(other: any): any;
+    _rski(options: any): Expr;
+    toString(opt: any): string;
+}
+export class Church extends Native {
+    constructor(n: any);
+    n: any;
+    arity: number;
+    equals(other: any): boolean;
+}
+export namespace globalOptions {
+    let terse: boolean;
+    let max: number;
+    let maxArgs: number;
+}
+export const native: {};
+declare class Named extends Expr {
+    /**
+       * @desc a constant named 'name'
+       * @param {String} name
+       */
+    constructor(name: string);
+    name: string;
+    toString(): string;
+}
+export {};

package/types/lib/parser.d.ts

@@ -0,0 +1,138 @@
+export class SKI {
+    /**
+     *
+     * @param {{
+     *    allow: string?,
+     *    numbers: boolean?,
+     *    lambdas: boolean?,
+     *    terms: { [key: string]: Expr|string}?,
+     *    annotate: boolean?,
+     * }} [options]
+     */
+    constructor(options?: {
+        allow: string | null;
+        numbers: boolean | null;
+        lambdas: boolean | null;
+        terms: {
+            [key: string]: Expr | string;
+        } | null;
+        annotate: boolean | null;
+    });
+    annotate: boolean;
+    known: {};
+    hasNumbers: boolean;
+    hasLambdas: boolean;
+    allow: any;
+    /**
+     *
+     * @param {Alias|String} term
+     * @param {Expr|String|[number, function(...Expr): Expr, {note: string?, fast: boolean?}]} [impl]
+     * @param {String} [note]
+     * @return {SKI} chainable
+     */
+    add(term: Alias | string, impl?: Expr | string | [number, (...args: Expr[]) => Expr, {
+        note: string | null;
+        fast: boolean | null;
+    }], note?: string): SKI;
+    maybeAdd(name: any, impl: any): this;
+    /**
+     * Restrict the interpreter to given terms. Terms prepended with '+' will be added
+     * and terms preceeded with '-' will be removed.
+     * @example ski.restrict('SK') // use the basis
+     * @example ski.restrict('+I') // allow I now
+     * @example ski.restrict('-SKI +BCKW' ); // switch basis
+     * @example ski.restrict('-foo -bar'); // forbid some user functions
+     * @param {string} spec
+     * @return {SKI} chainable
+     */
+    restrict(spec: string): SKI;
+    /**
+     *
+     * @param {string} spec
+     * @return {string}
+     */
+    showRestrict(spec?: string): string;
+    /**
+     *
+     * @param {String} name
+     * @return {SKI}
+     */
+    remove(name: string): SKI;
+    /**
+     *
+     * @return {{[key:string]: Native|Alias}}
+     */
+    getTerms(): {
+        [key: string]: Native | Alias;
+    };
+    /**
+     *
+     * @param {string} source
+     * @param {{[keys: string]: Expr}} vars
+     * @param {{numbers: boolean?, lambdas: boolean?, allow: string?}} options
+     * @return {Expr}
+     */
+    parse(source: string, vars?: {
+        [keys: string]: Expr;
+    }, options?: {
+        numbers: boolean | null;
+        lambdas: boolean | null;
+        allow: string | null;
+    }): Expr;
+    /**
+     *
+     * @param {String} source S(KI)I
+     * @param {{[keys: string]: Expr}} vars
+     * @param {{numbers: boolean?, lambdas: boolean?, allow: string?}} options
+     * @return {Expr} parsed expression
+     */
+    parseLine(source: string, vars?: {
+        [keys: string]: Expr;
+    }, options?: {
+        numbers: boolean | null;
+        lambdas: boolean | null;
+        allow: string | null;
+    }): Expr;
+    toJSON(): {
+        allow: string;
+        numbers: boolean;
+        lambdas: boolean;
+        terms: {
+            [key: string]: Native | Alias;
+        };
+        annotate: boolean;
+    };
+}
+export namespace SKI {
+    /**
+     * Create free var(s) for subsequent use
+     * @param {String} names
+     * @return {FreeVar[]}
+     */
+    export function free(...names: string): FreeVar[];
+    /**
+     * Convert a number to Church encoding
+     * @param {number} n
+     * @return {Church}
+     */
+    export function church(n: number): Church;
+    export namespace classes {
+        export { Expr };
+        export { Native };
+        export { Alias };
+        export { FreeVar };
+        export { Lambda };
+        export { Church };
+    }
+    export { native };
+    export { globalOptions as options };
+    export let lambdaPlaceholder: Native;
+}
+import { Alias } from "./expr";
+import { Expr } from "./expr";
+import { Native } from "./expr";
+import { FreeVar } from "./expr";
+import { Church } from "./expr";
+import { Lambda } from "./expr";
+import { native } from "./expr";
+import { globalOptions } from "./expr";

package/types/lib/quest.d.ts

@@ -0,0 +1,139 @@
+export type CaseResult = {
+    pass: boolean;
+    reason: string | null;
+    steps: number;
+    start: typeof import("./expr").Expr;
+    found: typeof import("./expr").Expr;
+    expected: typeof import("./expr").Expr;
+    note: string | null;
+    args: typeof import("./expr").Expr[];
+    case: Case;
+};
+/**
+ * @typedef {{
+ *   pass: boolean,
+ *   reason: string?,
+ *   steps: number,
+ *   start: Expr,
+ *   found: Expr,
+ *   expected: Expr,
+ *   note: string?,
+ *   args: Expr[],
+ *   case: Case
+ * }} CaseResult
+ */
+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?,
+     *    cases: [{max: number?, note: string?, feedInput: boolean, lambdas: boolean?}|string[], ...string[][]]?
+     * }} options
+     */
+    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: [{
+            max: number | null;
+            note: string | null;
+            feedInput: boolean;
+            lambdas: boolean | null;
+        } | string[], ...string[][]] | null;
+    });
+    engine: SKI;
+    engineFull: SKI;
+    restrict: {
+        allow: string;
+        numbers: boolean;
+        lambdas: any;
+    };
+    vars: {};
+    subst: string[] | (string & any[]);
+    input: any[];
+    varsFull: {};
+    cases: any[];
+    title: string;
+    descr: string;
+    meta: {
+        title: string | null;
+        descr: string | null;
+    };
+    /**
+     *   Display allowed terms based on what engine thinks of this.vars + this.restrict.allow
+     *   @return {string}
+     */
+    allowed(): string;
+    addInput(term: any): void;
+    /**
+     *
+     * @param {{} | string} opt
+     * @param {string} terms
+     * @return {Quest}
+     */
+    add(opt: {} | string, ...terms: string): Quest;
+    /**
+     * @description Statefully parse a list of strings into expressions or fancy aliases thereof.
+     * @param {string[]} input
+     * @return {{terms: Expr[], weight: number}}
+     */
+    prepare(...input: string[]): {
+        terms: typeof import("./expr").Expr[];
+        weight: number;
+    };
+    /**
+     *
+     * @param {string} input
+     * @return {{
+     *             expr: Expr?,
+     *             pass: boolean,
+     *             details: CaseResult[],
+     *             exception: Error?,
+     *             steps: number,
+     *             input: Expr[]|string[],
+     *             weight: number?
+     *         }}
+     */
+    check(...input: string): {
+        expr: typeof import("./expr").Expr | null;
+        pass: boolean;
+        details: CaseResult[];
+        exception: Error | null;
+        steps: number;
+        input: typeof import("./expr").Expr[] | string[];
+        weight: number | null;
+    };
+    /**
+       *
+       * @return {TestCase[]}
+       */
+    show(): TestCase[];
+}
+declare class Case {
+    constructor(input: any, options: any);
+    max: any;
+    note: any;
+    vars: any;
+    input: any;
+    engine: any;
+    parse(src: any): import("./expr").Lambda;
+    /**
+     * @param {Expr} expr
+     * @return {CaseResult}
+     */
+    check(...expr: typeof import("./expr").Expr): CaseResult;
+}
+import { SKI } from "./parser";
+export {};

package/types/lib/util.d.ts

@@ -0,0 +1,13 @@
+export class Tokenizer {
+    constructor(...terms: any[]);
+    rex: RegExp;
+    /**
+       *
+       * @param {string} str
+       * @return {string[]}
+       */
+    split(str: string): string[];
+}
+export function restrict(set: any, spec: any): any;
+export function missingIndices(arr: any, set: any): any;
+export function isSubset(a: any, b: any): boolean;