@dallaylaen/ski-interpreter 2.0.0 → 2.1.0

package/lib/expr.js

@@ -1,17 +1,40 @@
 'use strict';
 
+const { unwrap, prepareWrapper } = require('./internal');
+
 const DEFAULTS = {
   max:     1000,
   maxArgs: 32,
 };
 
+/**
+ * @template T
+ * @typedef {T | { value: T?, action: string } | null} ActionWrapper
+ */
+const control = {
+  descend: prepareWrapper('descend'),
+  prune:   prepareWrapper('prune'),
+  stop:    prepareWrapper('stop'),
+};
+
 /**
  * @typedef {Expr | function(Expr): Partial} Partial
  */
 
 class Expr {
   /**
-   *  @descr A generic combinatory logic expression.
+   *  @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] // TODO proper type
    */
   constructor () {
     if (new.target === Expr)
@@ -25,7 +48,10 @@ class Expr {
    * @return {Expr}
    */
   apply (...args) {
-    return args.length > 0 ? new App(this, ...args) : this;
+    let expr = this;
+    for (const arg of args)
+      expr = new App(expr, arg);
+    return expr;
   }
 
   /**
@@ -66,7 +92,36 @@ class Expr {
   }
 
   /**
-   * @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 (initial, combine) {
+    const [value, _] = unwrap(this._fold(initial, combine));
+    return value ?? initial;
+  }
+
+  _fold (initial, combine) {
+    return combine(initial, this);
+  }
+
+  /**
+   * @desc rough estimate of the complexity of the term
    * @return {number}
    */
   weight () {
@@ -85,7 +140,7 @@ 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,
@@ -105,6 +160,14 @@ class Expr {
     return out;
   }
 
+  /**
+   *
+   * @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
+   */
   _infer (options, preArgs = [], steps = 0) {
     if (preArgs.length > options.maxArgs || steps > options.max)
       return { normal: false, steps };
@@ -130,7 +193,7 @@ class Expr {
 
     // adding more args won't help, bail out
     // if we're an App, the App's _infer will take care of further args
-    if (this._firstVar())
+    if (this.unroll()[0] instanceof FreeVar)
       return { normal: false, steps };
 
     // try adding more arguments, maybe we'll get a normal form then
@@ -138,18 +201,23 @@ class Expr {
     return this.apply(push)._infer(options, [...preArgs, push], steps);
   }
 
-  _aslist () {
+  /**
+   * @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 () {
     // currently only used by infer() but may be useful
     // to convert binary App trees to n-ary or smth
     return [this];
   }
 
-  _firstVar () {
-    // boolean, whether the expression starts with a free variable
-    // only used by infer() as a shortcut to this._aslist()[0] instanceof FreeVar
-    return false;
-  }
-
   /**
    * @desc Returns a series of lambda terms equivalent to the given expression,
    *       up to the provided computation steps limit,
@@ -172,7 +240,14 @@ class Expr {
    * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
    */
   * toLambda (options = {}) {
-    const expr = naiveCanonize(this, options);
+    const expr = this.traverse(e => {
+      if (e instanceof FreeVar || e instanceof App || e instanceof Lambda || e instanceof Alias)
+        return null; // no change
+      const guess = e.infer({ max: options.max, maxArgs: options.maxArgs });
+      if (!guess.normal)
+        throw new Error('Failed to infer an equivalent  lambda term for ' + e);
+      return guess.expr;
+    }) ?? this;
     yield * simplifyLambda(expr, options);
   }
 
@@ -183,7 +258,7 @@ 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 = {}) {
@@ -202,6 +277,12 @@ class Expr {
     }
   }
 
+  /**
+   * @desc Internal method for toSKI, which performs one step of the conversion.
+   * @param {{max: number, steps: number}} options
+   * @returns {Expr}
+   * @private
+   */
   _rski (options) {
     return this;
   }
@@ -394,6 +475,12 @@ class Expr {
     return false;
   }
 
+  /**
+   * @desc Whether the expression can be printed without a space when followed by arg.
+   * @param {Expr} arg
+   * @returns {boolean}
+   * @private
+   */
   _unspaced (arg) {
     return this._braced(true);
   }
@@ -431,7 +518,6 @@ class Expr {
    * @example foo.format({ inventory: { T } }) // use T as a named term, expand all others
    *
    */
-
   format (options = {}) {
     const fallback = options.html
       ? {
@@ -463,28 +549,37 @@ class Expr {
     }, 0);
   }
 
+  /**
+   * @desc Internal method for format(), which performs the actual formatting.
+   * @param {Object} options
+   * @param {number} nargs
+   * @returns {string}
+   * @private
+   */
   _format (options, nargs) {
     throw new Error( 'No _format() method defined in class ' + this.constructor.name );
   }
 
   // output: string[] /* appended */, inventory: { [key: string]: Expr }, seen: Set<Expr>
   _declare (output, inventory, seen) {}
+
+  toJSON () {
+    return this.format();
+  }
 }
 
 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, ...args) {
-    if (args.length === 0)
-      throw new Error('Attempt to create an application with no arguments (likely interpreter bug)');
+  constructor (fun, arg) {
     super();
 
-    this.arg = args.pop();
-    this.fun = args.length ? new App(fun, ...args) : fun;
+    this.arg = arg;
+    this.fun = fun;
     this.final = false;
     this.arity = this.fun.arity > 0 ? this.fun.arity - 1 : 0;
   }
@@ -509,7 +604,7 @@ class App extends Expr {
       return proxy;
     steps = proxy.steps; // reimport extra iterations
 
-    const [first, ...list] = this._aslist();
+    const [first, ...list] = this.unroll();
     if (!(first instanceof FreeVar))
       return { normal: false, steps }
     // TODO maybe do it later
@@ -535,17 +630,13 @@ class App extends Expr {
     return {
       normal: true,
       steps,
-      ...maybeLambda(preArgs, new App(first, ...out), {
+      ...maybeLambda(preArgs, first.apply(...out), {
         discard,
         duplicate,
       }),
     };
   }
 
-  _firstVar () {
-    return this.fun._firstVar();
-  }
-
   expand () {
     return this.fun.expand().apply(this.arg.expand());
   }
@@ -568,6 +659,21 @@ class App extends Expr {
     return predicate(this) || this.fun.any(predicate) || this.arg.any(predicate);
   }
 
+  _fold (initial, combine) {
+    const [value = initial, action = 'descend'] = unwrap(combine(initial, this));
+    if (action === 'prune')
+      return value;
+    if (action === 'stop')
+      return control.stop(value);
+    const [fValue = value, fAction = 'descend'] = unwrap(this.fun._fold(value, combine));
+    if (fAction === 'stop')
+      return control.stop(fValue);
+    const [aValue = fValue, aAction = 'descend'] = unwrap(this.arg._fold(fValue, combine));
+    if (aAction === 'stop')
+      return control.stop(aValue);
+    return aValue;
+  }
+
   subst (search, replace) {
     const fun = this.fun.subst(search, replace);
     const arg = this.arg.subst(search, replace);
@@ -622,13 +728,8 @@ class App extends Expr {
     }
   }
 
-  split () {
-    // leftover from array-based older design
-    return [this.fun, this.arg];
-  }
-
-  _aslist () {
-    return [...this.fun._aslist(), this.arg];
+  unroll () {
+    return [...this.fun.unroll(), this.arg];
   }
 
   /**
@@ -740,10 +841,6 @@ class FreeVar extends Named {
     return 0;
   }
 
-  _firstVar () {
-    return true;
-  }
-
   diff (other, swap = false) {
     if (!(other instanceof FreeVar))
       return super.diff(other, swap);
@@ -899,6 +996,18 @@ class Lambda extends Expr {
     return predicate(this) || this.impl.any(predicate);
   }
 
+  _fold (initial, combine) {
+    const [value = initial, action = 'descend'] = unwrap(combine(initial, this));
+    if (action === 'prune')
+      return value;
+    if (action === 'stop')
+      return control.stop(value);
+    const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
+    if (iAction === 'stop')
+      return control.stop(iValue);
+    return iValue ?? value;
+  }
+
   subst (search, replace) {
     if (search === this.arg)
       return null;
@@ -920,14 +1029,14 @@ class Lambda extends Expr {
     if (!impl.any(e => e === this.arg))
       return native.K.apply(impl);
     if (impl instanceof App) {
-      const [fst, snd] = impl.split();
+      const { fun, arg } = impl;
       // try eta reduction
-      if (snd === this.arg && !fst.any(e => e === this.arg))
-        return fst._rski(options);
+      if (arg === this.arg && !fun.any(e => e === this.arg))
+        return fun._rski(options);
       // fall back to S
       return native.S.apply(
-        (new Lambda(this.arg, fst))._rski(options),
-        (new Lambda(this.arg, snd))._rski(options)
+        (new Lambda(this.arg, fun))._rski(options),
+        (new Lambda(this.arg, arg))._rski(options)
       );
     }
     throw new Error('Don\'t know how to convert to SKI' + this);
@@ -1056,6 +1165,18 @@ class Alias extends Named {
     return predicate(this) || this.impl.any(predicate);
   }
 
+  _fold (initial, combine) {
+    const [value = initial, action = 'descend'] = unwrap(combine(initial, this));
+    if (action === 'prune')
+      return value;
+    if (action === 'stop')
+      return control.stop(value);
+    const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
+    if (iAction === 'stop')
+      return control.stop(iValue);
+    return iValue ?? value;
+  }
+
   subst (search, replace) {
     if (this === search)
       return replace;
@@ -1078,10 +1199,6 @@ class Alias extends Named {
     return { expr: this.impl, steps: 0, changed: true };
   }
 
-  _firstVar () {
-    return this.impl._firstVar();
-  }
-
   diff (other, swap = false) {
     if (this === other)
       return null;
@@ -1230,23 +1347,6 @@ function maybeLambda (args, expr, caps = {}) {
   };
 }
 
-function naiveCanonize (expr) {
-  if (expr instanceof App)
-    return naiveCanonize(expr.fun).apply(naiveCanonize(expr.arg));
-
-  if (expr instanceof Lambda)
-    return new Lambda(expr.arg, naiveCanonize(expr.impl));
-
-  if (expr instanceof Alias)
-    return naiveCanonize(expr.impl);
-
-  const canon = expr.infer();
-  if (canon.expr)
-    return canon.expr;
-
-  throw new Error('Failed to canonize expression: ' + expr);
-}
-
 function nthvar (n) {
   return new FreeVar('abcdefgh'[n] ?? 'x' + n);
 }
@@ -1284,7 +1384,7 @@ function * simplifyLambda (expr, options = {}, state = { steps: 0 }) {
   // fun * arg Descartes product
   if (expr instanceof App) {
     // try to split into fun+arg, then try canonization but exposing each step
-    let [fun, arg] = expr.split();
+    let { fun, arg } = expr;
 
     for (const term of simplifyLambda(fun, options, state)) {
       const candidate = term.expr.apply(arg);
@@ -1312,5 +1412,6 @@ function * simplifyLambda (expr, options = {}, state = { steps: 0 }) {
 
 Expr.declare = declare;
 Expr.native = native;
+Expr.control = control;
 
-module.exports = { Expr, App, FreeVar, Lambda, Native, Alias, Church };
+module.exports = { Expr, App, Named, FreeVar, Lambda, Native, Alias, Church };

package/lib/extras.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const { Expr } = require('./expr')
+
+/**
+ * @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[][]}}
+ */
+function search (seed, options, predicate) {
+  const {
+    depth = 16,
+    infer = true,
+    progressInterval = 1000,
+  } = options;
+  const hasSeen = infer && !options.noskip;
+
+  // cache[i] = ith generation, 0 is empty
+  const cache = [[]];
+  let total = 0;
+  let probed = 0;
+  const seen = {};
+
+  const maybeProbe = term => {
+    total++;
+    const props = infer ? term.infer({ max: options.max, maxArgs: options.maxArgs }) : null;
+    if (hasSeen && props.expr) {
+      if (seen[props.expr])
+        return { res: -1 };
+      seen[props.expr] = true;
+    }
+    probed++;
+    const res = predicate(term, props);
+    return { res, props };
+  };
+
+  // sieve through the seed
+  for (const term of seed) {
+    const { res } = maybeProbe(term);
+    if (res > 0)
+      return { expr: term, total, probed, gen: 1 };
+    else if (res < 0)
+      continue;
+
+    cache[0].push(term);
+  }
+
+  let lastProgress;
+
+  for (let gen = 1; gen < depth; gen++) {
+    if (options.progress) {
+      options.progress({ gen, total, probed, step: true });
+      lastProgress = total;
+    }
+    for (let i = 0; i < gen; i++) {
+      for (const a of cache[gen - i - 1] || []) {
+        for (const b of cache[i] || []) {
+          if (total >= options.tries)
+            return { total, probed, gen, ...(options.retain ? { cache } : {}) };
+          if (options.progress && total - lastProgress >= progressInterval) {
+            options.progress({ gen, total, probed, step: false });
+            lastProgress = total;
+          }
+          const term = a.apply(b);
+          const { res, props } = maybeProbe(term);
+
+          if (res > 0)
+            return { expr: term, total, probed, gen, ...(options.retain ? { cache } : {}) };
+          else if (res < 0)
+            continue;
+
+          // if the term is not reducible, it is more likely to be a dead end, so we push it further away
+          const offset = infer
+            ? ((props.expr ? 0 : 3) + (props.dup ? 1 : 0) + (props.proper ? 0 : 1))
+            : 0;
+          if (!cache[gen + offset])
+            cache[gen + offset] = [];
+          cache[gen + offset].push(term);
+        }
+      }
+    }
+  }
+
+  return { total, probed, gen: depth, ...(options.retain ? { cache } : {}) };
+}
+
+/**
+ * @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}
+ */
+function deepFormat (obj, options = {}) {
+  if (obj instanceof Expr)
+    return obj.format(options);
+  if (Array.isArray(obj))
+    return obj.map(deepFormat);
+  if (typeof obj !== 'object' || obj === null || obj.constructor !== Object)
+    return obj;
+
+  // default = plain object
+  const out = {};
+  for (const key in obj)
+    out[key] = deepFormat(obj[key]);
+
+  return out;
+}
+
+module.exports = { search, deepFormat };

package/lib/internal.js

@@ -0,0 +1,105 @@
+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) {
+    const src = '$|(\\s+)|' + terms
+      .map(s => '(?:' + s + ')')
+      .sort((a, b) => b.length - a.length)
+      .join('|');
+    this.rex = new RegExp(src, 'gys');
+  }
+
+  /**
+   * @desc Split the given string into tokens according to the terms specified in the constructor.
+   * @param {string} str
+   * @return {string[]}
+   */
+  split (str) {
+    this.rex.lastIndex = 0;
+    const list = [...str.matchAll(this.rex)];
+
+    // did we parse everything?
+    const eol = list.pop();
+    const last = eol?.index ?? 0;
+
+    if (last !== str.length) {
+      throw new Error('Unknown tokens at pos ' + last + '/' + str.length
+                + ' starting with ' + str.substring(last));
+    }
+
+    // skip whitespace
+    return list.filter(x => x[1] === undefined).map(x => x[0]);
+  }
+}
+
+const tokRestrict = new Tokenizer('[-=+]', '[A-Z]', '\\b[a-z_][a-z_0-9]*\\b');
+
+/**
+ * @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>}
+ */
+function restrict (set, spec) {
+  if (!spec)
+    return set;
+  let out = new Set([...set]);
+  const act = {
+    '=': sym => { out = new Set([sym]); mode = '+'; },
+    '+': sym => { out.add(sym); },
+    '-': sym => { out.delete(sym); },
+  };
+
+  let mode = '=';
+  for (const sym of tokRestrict.split(spec)) {
+    if (act[sym])
+      mode = sym;
+    else
+      act[mode](sym);
+  }
+  return out;
+}
+
+class ActionWrapper {
+  /**
+   * @template T
+   * @param {T} value
+   * @param {string} action
+   */
+  constructor (value, action) {
+    this.value = value;
+    this.action = action;
+  }
+}
+
+/**
+ * @private
+ * @template T
+ * @param {T|ActionWrapper<T>} value
+ * @returns {[T?, string|undefined]}
+ */
+function unwrap (value) {
+  if (value instanceof ActionWrapper)
+    return [value.value ?? undefined, value.action];
+  return [value ?? undefined, undefined];
+}
+
+/**
+ *
+ * @private
+ * @template T
+ * @param {string} action
+ * @returns {function(T): ActionWrapper<T>}
+ */
+function prepareWrapper (action) {
+  return value => new ActionWrapper(value, action);
+}
+
+module.exports = { Tokenizer, restrict, unwrap, prepareWrapper };