@dallaylaen/ski-interpreter 2.0.0 → 2.1.0

package/lib/parser.js

@@ -3,10 +3,10 @@
  */
 'use strict';
 
-const { Tokenizer, restrict } = require('./util');
+const { Tokenizer, restrict } = require('./internal');
 const classes = require('./expr');
 
-const { Expr, Native, Alias, FreeVar, Lambda, Church } = classes;
+const { Expr, Named, Native, Alias, FreeVar, Lambda, Church } = classes;
 const { native, declare } = Expr;
 
 class Empty extends Expr {
@@ -271,20 +271,29 @@ class SKI {
     let expr = new Empty();
     for (const item of lines) {
       const [_, save, str] = item.match(/^(?:\s*([A-Z]|[a-z][a-z_0-9]*)\s*=\s*)?(.*)$/s);
+
       if (expr instanceof Alias)
         expr.outdated = true;
-      expr = this.parseLine(str, jar, options);
+      expr = (str === '' && save !== undefined)
+        ? new FreeVar(save, options.scope)
+        : this.parseLine(str, jar, options);
 
       if (save !== undefined) {
         if (jar[save] !== undefined)
           throw new Error('Attempt to redefine a known term: ' + save);
-        expr = new Alias(save, expr);
+        expr = maybeAlias(save, expr);
         jar[save] = expr;
       }
 
       // console.log('parsed line:', item, '; got:', expr,'; jar now: ', jar);
     }
 
+    expr.context = {
+      env:    jar, // also contains pre-parsed terms
+      scope:  options.scope,
+      src:    source,
+      parser: this,
+    };
     return expr;
   }
 
@@ -368,6 +377,12 @@ class SKI {
   }
 }
 
+function maybeAlias (name, expr) {
+  if (expr instanceof Named && expr.name === name)
+    return expr;
+  return new Alias(name, expr);
+}
+
 // Create shortcuts for common terms
 
 SKI.classes = classes;
@@ -414,5 +429,6 @@ for (const name in native)
   SKI[name] = native[name];
 SKI.native = native;
 SKI.declare = declare;
+SKI.control = Expr.control;
 
 module.exports = { SKI };

package/lib/quest.js

@@ -35,6 +35,10 @@ const { Expr, FreeVar, Alias, Lambda } = SKI.classes;
  * } TestCase
  */
 
+/**
+ * @typedef {string | {name: string, fancy?: string, allow?: string, numbers?: boolean, lambdas?: boolean}} InputSpec
+ */
+
 /**
  * @typedef {{
  *   pass: boolean,
@@ -51,40 +55,60 @@ 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 = {}) {
-    const { input, vars, cases, allow, numbers, lambdas, subst, engine, engineFull, ...meta } = options;
+    const { input, cases, allow, numbers, lambdas, engine, engineFull, ...meta } = options;
+    const env = options.env ?? options.vars; // backwards compatibility
 
     //
     this.engine = engine ?? new SKI();
     this.engineFull = engineFull ?? new SKI();
     this.restrict = { allow, numbers: numbers ?? false, lambdas: lambdas ?? false };
-    this.vars = {};
-    this.subst = Array.isArray(subst) ? subst : [subst ?? 'phi'];
+    this.env = {};
 
     const jar = {};
 
-    // options.vars is a list of expressions.
-    // we suck all free variables + all term declarations from there into this.vars
+    // option.env is a list of expressions.
+    // we suck all free variables + all term declarations from there into this.env
     // to feed it later to every case's parser.
-    for (const term of vars ?? []) {
+    for (const term of env ?? []) {
       const expr = this.engineFull.parse(term, { env: jar, scope: this });
       if (expr instanceof SKI.classes.Alias)
-        this.vars[expr.name] = new Alias(expr.name, expr.impl, { terminal: true, canonize: false });
+        this.env[expr.name] = new Alias(expr.name, expr.impl, { terminal: true, canonize: false });
         // Canonized aliases won't expand with insufficient arguments,
         // causing correct solutions to fail, so alas...
       else if (expr instanceof SKI.classes.FreeVar)
-        this.vars[expr.name] = expr;
+        this.env[expr.name] = expr;
       else
         throw new Error('Unsupported given variable type: ' + term);
     }
@@ -94,20 +118,21 @@ class Quest {
       this.addInput(term);
     if (!this.input.length)
       throw new Error('Quest needs at least one input placeholder');
-    if (subst)
-      this.input[0].fancy = this.subst[0];
 
-    this.varsFull = { ...this.vars, ...jar };
+    this.envFull = { ...this.env, ...jar };
     for (const term of this.input) {
-      if (term.name in this.varsFull)
-        throw new Error('input placeholder name is duplicated or clashes with vars: ' + term.name);
-      this.varsFull[term.name] = term.placeholder;
+      if (term.name in this.envFull)
+        throw new Error('input placeholder name is duplicated or clashes with env: ' + term.name);
+      this.envFull[term.name] = term.placeholder;
     }
 
+    // NOTE meta is a local variable, can mutate
+    // NOTE title/descr are old name/intro respectively, kept for backwards compatibility
     this.cases = [];
-    this.title = meta.title;
-    meta.descr = list2str(meta.descr);
-    this.descr = meta.descr;
+    this.name = meta.name ?? meta.title;
+    meta.intro = list2str(meta.intro ?? meta.descr);
+    this.intro = meta.intro;
+    this.id = meta.id;
     this.meta = meta;
 
     for (const c of cases ?? [])
@@ -115,16 +140,16 @@ class Quest {
   }
 
   /**
-   *   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 () {
     const allow = this.restrict.allow ?? '';
-    const vars = Object.keys(this.vars).sort();
+    const env  = Object.keys(this.env).sort();
     // In case vars are present and restrictions aren't, don't clutter the output with all the known terms
     return allow
-      ? this.engine.showRestrict(allow + '+' + vars.join(' '))
-      : vars.map( s => '+' + s).join(' ');
+      ? this.engine.showRestrict(allow + '+' + env.join(' '))
+      : env.map( s => '+' + s).join(' ');
   }
 
   addInput (term) {
@@ -152,7 +177,7 @@ class Quest {
       opt = { ...opt };
 
     opt.engine = opt.engine  ?? this.engineFull;
-    opt.vars = opt.vars ?? this.varsFull;
+    opt.env = opt.env ?? this.envFull;
 
     const input = this.input.map( t => t.placeholder );
     this.cases.push(
@@ -174,7 +199,7 @@ class Quest {
 
     let weight = 0;
     const prepared = [];
-    const jar = { ...this.vars };
+    const jar = { ...this.env };
     for (let i = 0; i < input.length; i++) {
       const spec = this.input[i];
       const impl = this.engine.parse(input[i], {
@@ -235,20 +260,20 @@ class Case {
    * @param {{
    *   max?: number,
    *   note?: string,
-   *   vars?: {[key:string]: Expr},
+   *   env?: {[key:string]: Expr},
    *   engine: SKI
    * }} options
    */
   constructor (input, options) {
     this.max = options.max ?? 1000;
     this.note = options.note;
-    this.vars = { ...(options.vars ?? {}) }; // note: scope already contains input placeholders
+    this.env = { ...(options.env ?? {}) }; // note: env already contains input placeholders
     this.input = input;
     this.engine = options.engine;
   }
 
   parse (src) {
-    return new Subst(this.engine.parse(src, { env: this.vars, scope: this }), this.input);
+    return new Subst(this.engine.parse(src, { env: this.env, scope: this }), this.input);
   }
 
   /**
@@ -266,7 +291,7 @@ class ExprCase extends Case {
    * @param {{
    *    max: number?,
    *    note: string?,
-   *    vars: {string: Expr}?,
+   *    env: {string: Expr}?,
    *    engine: SKI?
    * }} options
    * @param {[e1: string, e2: string]} terms
@@ -373,27 +398,32 @@ 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, vars) {
+  constructor (expr, env) {
     this.expr = expr;
-    this.vars = vars;
+    this.env = env;
   }
 
   apply (list) {
-    if (list.length !== this.vars.length)
-      throw new Error('Subst: expected ' + this.vars.length + ' terms, got ' + list.length);
+    if (list.length !== this.env.length)
+      throw new Error('Subst: expected ' + this.env.length + ' terms, got ' + list.length);
 
     let expr = this.expr;
-    for (let i = 0; i < this.vars.length; i++)
-      expr = expr.subst(this.vars[i], list[i]) ?? expr;
+    for (let i = 0; i < this.env.length; i++)
+      expr = expr.subst(this.env[i], list[i]) ?? expr;
 
     return expr;
   }
 }
 
+/**
+ * @desc Concatenate long strings represented as arrays, or just pass along if already string or undefined.
+ * @param {string|Array<string>|undefined} str
+ * @returns {string|undefined}
+ */
 function list2str (str) {
-  if (str === undefined)
+  if (str === undefined || typeof str === 'string')
     return str;
   return Array.isArray(str) ? str.join(' ') : '' + str;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.0.0",
+  "version": "2.1.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",
@@ -15,7 +15,7 @@
     "ski": "bin/ski.js"
   },
   "scripts": {
-    "lint": "npx eslint lib --ext .js,.ts",
+    "lint": "npx eslint --ext .js,.ts lib test index.js bin",
     "types": "npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly --outDir types",
     "test": "npx nyc mocha",
     "minify": "npx esbuild --bundle ./index.js --outfile=docs/build/js/ski-interpreter.min.js --minify --sourcemap",

package/types/index.d.ts

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

package/types/lib/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
@@ -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,38 @@ export class Expr {
             [x: string]: Expr;
         };
     }): string;
-    _format(options: any, nargs: any): void;
+    /**
+     * @desc Internal method for format(), which performs the actual formatting.
+     * @param {Object} options
+     * @param {number} nargs
+     * @returns {string}
+     * @private
+     */
+    private _format;
     _declare(output: any, inventory: any, seen: any): void;
+    toJSON(): string;
 }
 export namespace Expr {
     export { declare };
     export { native };
+    export { control };
 }
 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 +396,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,6 +460,7 @@ 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;
@@ -391,7 +468,7 @@ export class Lambda extends Expr {
     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 +497,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 +533,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}}
@@ -491,14 +569,9 @@ declare function declare(inventory: Expr[]): string[];
 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;
 }
 export {};

package/types/lib/extras.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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;
+import { Expr } from "./expr";