@dallaylaen/ski-interpreter 1.2.0 → 2.0.0

package/lib/expr.js

@@ -1,13 +1,14 @@
 'use strict';
 
-const { skipDup, isSubset } = require('./util');
-
-const globalOptions = {
-  terse:   true,
+const DEFAULTS = {
   max:     1000,
   maxArgs: 32,
 };
 
+/**
+ * @typedef {Expr | function(Expr): Partial} Partial
+ */
+
 class Expr {
   /**
    *  @descr A generic combinatory logic expression.
@@ -18,103 +19,50 @@ class Expr {
   }
 
   /**
-     * postprocess term after parsing. typically return self but may return other term or die
-     * @return {Expr}
-     */
-  postParse () {
-    return this;
-  }
-
-  /**
-     * @desc apply self to zero or more terms and return the resulting term,
-     * without performing any calculations whatsoever
-     * @param {Expr} args
-     * @return {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) {
     return args.length > 0 ? new App(this, ...args) : this;
   }
 
   /**
-     * expand all terms but don't perform any calculations
-     * @return {Expr}
-     */
+   * expand all terms but don't perform any calculations
+   * @return {Expr}
+   */
   expand () {
     return this;
   }
 
-  /**
-   * @desc return all free variables within the term
-   * @return {Set<FreeVar>}
-   */
-  freeVars () {
-    const symbols = this.getSymbols();
-    const out = new Set();
-    for (const [key, _] of symbols) {
-      if (key instanceof FreeVar)
-        out.add(key);
-    }
-    return out;
-  }
-
-  hasLambda () {
-    const sym = this.getSymbols();
-    return sym.has(Expr.lambdaPlaceholder);
-  }
-
   freeOnly () {
-    for (const [key, _] of this.getSymbols()) {
-      if (!(key instanceof FreeVar))
-        return false;
-    }
-    return true;
+    return !this.any(e => !(e instanceof FreeVar || e instanceof App));
   }
 
   /**
-   * @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>}
+   * @desc Traverse the expression tree, applying change() to each node.
+   *       If change() returns an Expr, the node is replaced with that value.
+   *       Otherwise, the node is left descended further (if applicable)
+   *       or left unchanged.
+   *
+   *       Returns null if no changes were made, or the new expression otherwise.
+   *
+   * @param {(e:Expr) => (Expr|null)} change
+   * @returns {Expr|null}
    */
-  getSymbols () {
-    // TODO better name!
-    return new Map([[this, 1]]);
+  traverse (change) {
+    return change(this);
   }
 
   /**
-   *   @desc Given a list of pairs of term, replaces every subtree
-   *         that is equivalent to the first term in pair with the second one.
-   *         If a simgle term is given, it is duplicated into a pair.
-   *
-   *   @example  S(SKK)(SKS).replace('I') = SII // we found 2 subtrees equivalent to I
-   *             and replaced them with I
+   * @desc Returns true if predicate() is true for any subterm of the expression, false otherwise.
    *
-   *   @param {(Expr | [find: Expr, replace: Expr])[]} terms
-   *   @param {Object} [opt] - options
-   *   @return {Expr}
+   * @param {(e: Expr) => boolean} predicate
+   * @returns {boolean}
    */
-  replace (terms, opt = {}) {
-    const pairs = [];
-    if (terms.length === 0)
-      return this; // nothing to replace, return self
-    for (const entry of terms) {
-      const pair = (Array.isArray(entry) ? entry : [entry, entry]);
-      pair[0] = pair[0].guess(opt).expr;
-      if (!pair[0])
-        throw new Error('Failed to canonize term ' + entry);
-      if (pair.length !== 2)
-        throw new Error('Expected a pair of terms to replace, got ' + entry);
-      pairs.push(pair);
-    }
-    return this._replace(pairs, opt) ?? this;
-  }
-
-  _replace (pairs, opt) {
-    const check = this.guess(opt).expr;
-    for (const [canon, term] of pairs) {
-      if (check.equals(canon))
-        return term;
-    }
-    return null;
+  any (predicate) {
+    return predicate(this);
   }
 
   /**
@@ -126,16 +74,16 @@ class Expr {
   }
 
   /**
-   * @desc Try to find an equivalent lambda term for the expression,
+   * @desc Try to empirically find an equivalent lambda term for the expression,
    *       returning also the term's arity and some other properties.
    *
-   *       This is used internally when declaring a Native term,
+   *       This is used internally when declaring a Native / Alias term,
    *       unless {canonize: false} is used.
    *
    *       As of current it only recognizes terms that have a normal form,
    *       perhaps after adding some variables. This may change in the future.
    *
-   *       Use lambdify() if you want to get a lambda term in any case.
+   *       Use toLambda() if you want to get a lambda term in any case.
    *
    * @param {{max: number?, maxArgs: number?}} options
    * @return {{
@@ -150,14 +98,14 @@ class Expr {
    *    dup?: Set<number>,
    * }}
    */
-  guess (options = {}) {
-    const max = options.max ?? globalOptions.max;
-    const maxArgs = options.maxArgs ?? globalOptions.maxArgs;
-    const out = this._guess({ max, maxArgs, index: 0 });
+  infer (options = {}) {
+    const max = options.max ?? DEFAULTS.max;
+    const maxArgs = options.maxArgs ?? DEFAULTS.maxArgs;
+    const out = this._infer({ max, maxArgs, index: 0 });
     return out;
   }
 
-  _guess (options, preArgs = [], steps = 0) {
+  _infer (options, preArgs = [], steps = 0) {
     if (preArgs.length > options.maxArgs || steps > options.max)
       return { normal: false, steps };
 
@@ -178,22 +126,27 @@ class Expr {
 
     // normal form != this, redo exercise
     if (next.steps !== 0)
-      return next.expr._guess(options, preArgs, steps);
+      return next.expr._infer(options, preArgs, steps);
 
+    // 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())
       return { normal: false, steps };
 
+    // try adding more arguments, maybe we'll get a normal form then
     const push = nthvar(preArgs.length + options.index);
-    return this.apply(push)._guess(options, [...preArgs, push], steps);
+    return this.apply(push)._infer(options, [...preArgs, push], steps);
   }
 
   _aslist () {
+    // 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
-    // used by guess()
+    // only used by infer() as a shortcut to this._aslist()[0] instanceof FreeVar
     return false;
   }
 
@@ -201,6 +154,12 @@ class Expr {
    * @desc Returns a series of lambda terms equivalent to the given expression,
    *       up to the provided computation steps limit,
    *       in decreasing weight order.
+   *
+   *       Unlike infer(), this method will always return something,
+   *       even if the expression has no normal form.
+   *
+   *       See also Expr.walk() and Expr.toSKI().
+   *
    * @param {{
    *   max?: number,
    *   maxArgs?: number,
@@ -212,17 +171,22 @@ class Expr {
    * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
    * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
    */
-  * lambdify (options = {}) {
+  * toLambda (options = {}) {
     const expr = naiveCanonize(this, options);
     yield * simplifyLambda(expr, options);
   }
 
   /**
-   * @desc same semantics as walk() but rewrite step by step instead of computing
+   * @desc Rewrite the expression into S, K, and I combinators step by step.
+   *     Returns an iterator yielding the intermediate expressions,
+   *     along with the number of steps taken to reach them.
+   *
+   *     See also Expr.walk() and Expr.toLambda().
+   *
    * @param {{max: number?}} options
    * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
    */
-  * rewriteSKI (options = {}) {
+  * toSKI (options = {}) {
     // TODO options.max is not actually max, it's the number of steps in one iteration
     let steps = 0;
     let expr = this;
@@ -242,23 +206,13 @@ class Expr {
     return this;
   }
 
-  /**
-     * Apply self to list of given args.
-     * Normally, only native combinators know how to do it.
-     * @param {Expr[]} args
-     * @return {Expr|null}
-     */
-  reduce (args) {
-    return null;
-  }
-
   /**
    * Replace all instances of plug in the expression with value and return the resulting expression,
    * or null if no changes could be made.
    * Lambda terms and applications will never match if used as plug
    * as they are impossible co compare without extensive computations.
    * Typically used on variables but can also be applied to other terms, e.g. aliases.
-   * See also Expr.replace().
+   * See also Expr.traverse().
    * @param {Expr} search
    * @param {Expr} replace
    * @return {Expr|null}
@@ -268,19 +222,42 @@ class Expr {
   }
 
   /**
-     * @desc iterate one step of calculation in accordance with known rules.
-     * @return {{expr: Expr, steps: number, changed: boolean}}
-     */
+   * @desc Apply term reduction rules, if any, to the given argument.
+   * A returned value of null means no reduction is possible.
+   * A returned value of Expr means the reduction is complete and the application
+   *     of this and arg can be replaced with the result.
+   * A returned value of a function means that further arguments are needed,
+   *     and can be cached for when they arrive.
+   *
+   * This method is between apply() which merely glues terms together,
+   *     and step() which reduces the whole expression.
+   *
+   * foo.invoke(bar) is what happens inside foo.apply(bar).step() before
+   *     reduction of either foo or bar is attempted.
+   *
+   * The name 'invoke' was chosen to avoid confusion with either 'apply' or 'reduce'.
+   *
+   * @param {Expr} arg
+   * @returns {Partial | null}
+   */
+  invoke (arg) {
+    return null;
+  }
+
+  /**
+   * @desc iterate one step of a calculation.
+   * @return {{expr: Expr, steps: number, changed: boolean}}
+   */
   step () { return { expr: this, steps: 0, changed: false } }
 
   /**
-     * @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}}
-     */
+   * @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 = {}, ...args) {
     if (opt instanceof Expr) {
       args.unshift(opt);
@@ -289,7 +266,7 @@ class Expr {
     let expr = args ? this.apply(...args) : this;
     let steps = opt.steps ?? 0;
     // make sure we make at least 1 step, to tell whether we've reached the normal form
-    const max = Math.max(opt.max ?? globalOptions.max, 1) + steps;
+    const max = Math.max(opt.max ?? DEFAULTS.max, 1) + steps;
     let final = false;
     for (; steps < max; ) {
       const next = expr.step();
@@ -306,11 +283,11 @@ class Expr {
   }
 
   /**
-     * 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}>}
-     */
+   * 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 = {}) {
     const max = options.max ?? Infinity;
     let steps = 0;
@@ -333,20 +310,49 @@ class Expr {
   }
 
   /**
+   * @desc True is the expressions are identical, false otherwise.
+   *       Aliases are expanded.
+   *       Bound variables in lambda terms are renamed consistently.
+   *       However, no reductions are attempted.
+   *
+   *       E.g. a->b->a == x->y->x is true, but a->b->a == K is false.
    *
    * @param {Expr} other
    * @return {boolean}
    */
   equals (other) {
-    if (this === other)
-      return true;
-    if (other instanceof Alias)
-      return other.equals(this);
-    return false;
+    return !this.diff(other);
   }
 
-  contains (other) {
-    return this === other || this.equals(other);
+  /**
+   * @desc Recursively compare two expressions and return a string
+   *       describing the first point of difference.
+   *       Returns null if expressions are identical.
+   *
+   *       Aliases are expanded.
+   *       Bound variables in lambda terms are renamed consistently.
+   *       However, no reductions are attempted.
+   *
+   *       Members of the FreeVar class are considered different
+   *       even if they have the same name, unless they are the same object.
+   *       To somewhat alleviate confusion, the output will include
+   *       the internal id of the variable in square brackets.
+   *
+   * @example  "K(S != I)" is the result of comparing "KS" and "KI"
+   * @example  "S(K([x[13] != x[14]]))K"
+   *
+   * @param {Expr} other
+   * @param {boolean} [swap]  If true, the order of expressions is reversed in the output.
+   * @returns {string|null}
+   */
+  diff (other, swap = false) {
+    if (this === other)
+      return null;
+    if (other instanceof Alias)
+      return other.impl.diff(this, !swap);
+    return swap
+      ? '[' + other + ' != ' + this  + ']'
+      : '[' + this  + ' != ' + other + ']';
   }
 
   /**
@@ -358,12 +364,13 @@ class Expr {
     comment = comment ? comment + ': ' : '';
     if (!(expected instanceof Expr))
       throw new Error(comment + 'attempt to expect a combinator to equal something else: ' + expected);
-    if (this.equals(expected))
-      return;
+    const diff = this.diff(expected);
+    if (!diff)
+      return; // all good
 
     // TODO wanna use AssertionError but webpack doesn't recognize it
     // still the below hack works for mocha-based tests.
-    const poorMans = new Error(comment + 'found term ' + this + ' but expected ' + expected);
+    const poorMans = new Error(comment + diff);
     poorMans.expected = expected + '';
     poorMans.actual = this + '';
     throw poorMans;
@@ -399,10 +406,11 @@ class Expr {
    *
    * @param   {Object} [options]  - formatting options
    * @param   {boolean} [options.terse]   - whether to use terse formatting (omitting unnecessary spaces and parentheses)
-   * @param   {boolean} [options.html]    - whether to default to HTML tags & entities
+   * @param   {boolean} [options.html]    - whether to default to HTML tags & entities.
+   *                                If a named term has fancyName property set, it will be used instead of name in this mode.
    * @param   {[string, string]} [options.brackets]  - wrappers for application arguments, typically ['(', ')']
    * @param   {[string, string]} [options.var]       - wrappers for variable names
-   *                                (will default to &lt;var&gt; and &lt;/var&gt; in html mode)
+   *                                (will default to &lt;var&gt; and &lt;/var&gt; in html mode).
    * @param   {[string, string, string]} [options.lambda]    - wrappers for lambda abstractions, e.g. ['&lambda;', '.', '']
    *                                where the middle string is placed between argument and body
    *                                default is ['', '->', ''] or ['', '-&gt;', ''] for html
@@ -425,14 +433,14 @@ class Expr {
    */
 
   format (options = {}) {
-    const defaults = options.html
+    const fallback = options.html
       ? {
         brackets: ['(', ')'],
         space:    ' ',
         var:      ['<var>', '</var>'],
         lambda:   ['', '-&gt;', ''],
         around:   ['', ''],
-        redex:    ['<b>', '</b>'],
+        redex:    ['', ''],
       }
       : {
         brackets: ['(', ')'],
@@ -443,14 +451,15 @@ class Expr {
         redex:    ['', ''],
       }
     return this._format({
-      terse:     options.terse    ?? globalOptions.terse,
-      brackets:  options.brackets ?? defaults.brackets,
-      space:     options.space    ?? defaults.space,
-      var:       options.var      ?? defaults.var,
-      lambda:    options.lambda   ?? defaults.lambda,
-      around:    options.around   ?? defaults.around,
-      redex:     options.redex    ?? defaults.redex,
+      terse:     options.terse    ?? true,
+      brackets:  options.brackets ?? fallback.brackets,
+      space:     options.space    ?? fallback.space,
+      var:       options.var      ?? fallback.var,
+      lambda:    options.lambda   ?? fallback.lambda,
+      around:    options.around   ?? fallback.around,
+      redex:     options.redex    ?? fallback.redex,
       inventory: options.inventory, // TODO better name
+      html:      options.html     ?? false,
     }, 0);
   }
 
@@ -484,25 +493,18 @@ class App extends Expr {
     return this.fun.weight() + this.arg.weight();
   }
 
-  getSymbols () {
-    const out = this.fun.getSymbols();
-    for (const [key, value] of this.arg.getSymbols())
-      out.set(key, (out.get(key) ?? 0) + value);
-    return out;
-  }
-
-  _guess (options, preArgs = [], steps = 0) {
+  _infer (options, preArgs = [], steps = 0) {
     if (preArgs.length > options.maxArgs || steps > options.max)
       return { normal: false, steps };
 
     /*
      * inside and App there are 3 main possibilities:
-     * 1) The parent guess() actually is able to do the job. Then we just proxy the result.
+     * 1) The parent infer() actually is able to do the job. Then we just proxy the result.
      * 2) Both `fun` and `arg` form good enough lambda terms. Then lump them together & return.
      * 3) We literally have no idea, so we just pick the shortest defined term from the above.
      */
 
-    const proxy = super._guess(options, preArgs, steps);
+    const proxy = super._infer(options, preArgs, steps);
     if (proxy.normal)
       return proxy;
     steps = proxy.steps; // reimport extra iterations
@@ -516,7 +518,7 @@ class App extends Expr {
     let duplicate = false;
     const out = [];
     for (const term of list) {
-      const guess = term._guess({
+      const guess = term._infer({
         ...options,
         maxArgs: options.maxArgs - preArgs.length,
         max:     options.max - steps,
@@ -544,22 +546,26 @@ class App extends Expr {
     return this.fun._firstVar();
   }
 
-  apply (...args) {
-    if (args.length === 0)
-      return this;
-    return new App(this, ...args);
-  }
-
   expand () {
     return this.fun.expand().apply(this.arg.expand());
   }
 
-  _replace (pairs, opt) {
-    const maybe = super._replace(pairs, opt);
-    if (maybe)
-      return maybe;
-    const [fun, arg] = this.split();
-    return (fun._replace(pairs, opt) ?? fun).apply(arg._replace(pairs, opt) ?? arg);
+  traverse (change) {
+    const replaced = change(this);
+    if (replaced instanceof Expr)
+      return replaced;
+
+    const fun = this.fun.traverse(change);
+    const arg = this.arg.traverse(change);
+
+    if (!fun && !arg)
+      return null; // no changes
+
+    return (fun ?? this.fun).apply(arg ?? this.arg);
+  }
+
+  any (predicate) {
+    return predicate(this) || this.fun.any(predicate) || this.arg.any(predicate);
   }
 
   subst (search, replace) {
@@ -576,34 +582,48 @@ class App extends Expr {
   step () {
     // normal reduction order: first try root, then at most 1 step
     if (!this.final) {
-      if (this.arity === 0) {
-        // aha! we have just fulfilled some previous function's argument demands
-        const reduced = this.fun.reduce([this.arg]);
-        // should always be true, but whatever
-        if (reduced)
-          return { expr: reduced, steps: 1, changed: true };
-      }
-      // now try recursing
-
+      // try to apply rewriting rules, if applicable, at first
+      const partial = this.fun.invoke(this.arg);
+      if (partial instanceof Expr)
+        return { expr: partial, steps: 1, changed: true };
+      else if (typeof partial === 'function')
+        this.invoke = partial; // cache for next time
+
+      // descend into the leftmost term
       const fun = this.fun.step();
       if (fun.changed)
         return { expr: fun.expr.apply(this.arg), steps: fun.steps, changed: true };
 
+      // descend into arg
       const arg = this.arg.step();
       if (arg.changed)
         return { expr: this.fun.apply(arg.expr), steps: arg.steps, changed: true };
 
-      this.final = true;
+      // mark as irreducible
+      this.final = true; // mark as irreducible at root
     }
+
     return { expr: this, steps: 0, changed: false };
   }
 
-  reduce (args) {
-    return this.fun.reduce([this.arg, ...args]);
+  invoke (arg) {
+    // propagate invocation towards the root term,
+    // caching partial applications as we go
+    const partial = this.fun.invoke(this.arg);
+    if (partial instanceof Expr)
+      return partial.apply(arg);
+    else if (typeof partial === 'function') {
+      this.invoke = partial;
+      return partial(arg);
+    } else {
+      // invoke = null => we're uncomputable, cache for next time
+      this.invoke = _ => null;
+      return null;
+    }
   }
 
   split () {
-    // pretend we are an elegant (cons fun arg) and not a sleazy imperative array
+    // leftover from array-based older design
     return [this.fun, this.arg];
   }
 
@@ -622,15 +642,17 @@ class App extends Expr {
     return this.fun._rski(options).apply(this.arg._rski(options));
   }
 
-  equals (other) {
+  diff (other, swap = false) {
     if (!(other instanceof App))
-      return super.equals(other);
-
-    return this.fun.equals(other.fun) && this.arg.equals(other.arg);
-  }
-
-  contains (other) {
-    return this.fun.contains(other) || this.arg.contains(other) || super.contains(other);
+      return super.diff(other, swap);
+
+    const fun = this.fun.diff(other.fun, swap);
+    if (fun)
+      return fun + '(...)';
+    const arg = this.arg.diff(other.arg, swap);
+    if (arg)
+      return this.fun + '(' + arg + ')';
+    return null;
   }
 
   _braced (first) {
@@ -660,9 +682,10 @@ class App extends Expr {
 
 class Named extends Expr {
   /**
-     * @desc a constant named 'name'
-     * @param {String} name
-     */
+   * @desc An abstract class representing a term named 'name'.
+   *
+   * @param {String} name
+   */
   constructor (name) {
     super();
     if (typeof name !== 'string' || name.length === 0)
@@ -680,18 +703,37 @@ class Named extends Expr {
   }
 
   _format (options, nargs) {
+    // NOTE fancyName is not yet official and may change name or meaning
+    const name = options.html ? this.fancyName ?? this.name : this.name;
     return this.arity > 0 && this.arity <= nargs
-      ? options.redex[0] + this.name + options.redex[1]
-      : this.name;
+      ? options.redex[0] + name + options.redex[1]
+      : name;
   }
 }
 
 let freeId = 0;
 
 class FreeVar extends Named {
-  constructor (name) {
+  /**
+   * @desc A named variable.
+   *
+   * Given the functional nature of combinatory logic, variables are treated
+   * as functions that we don't know how to evaluate just yet.
+   *
+   * By default, two different variables even with the same name are considered different.
+   * They display it via a hidden id property.
+   *
+   * If a scope object is given, however, two variables with the same name and scope
+   * are considered identical.
+   *
+   * @param {string} name - name of the variable
+   * @param {any} scope - an object representing where the variable belongs to.
+   */
+  constructor (name, scope) {
     super(name);
     this.id = ++freeId;
+    // TODO temp compatibility mode
+    this.scope = scope === undefined ? this : scope;
   }
 
   weight () {
@@ -702,82 +744,76 @@ class FreeVar extends Named {
     return true;
   }
 
+  diff (other, swap = false) {
+    if (!(other instanceof FreeVar))
+      return super.diff(other, swap);
+    if (this.name === other.name && this.scope === other.scope)
+      return null;
+    const lhs = this.name + '[' + this.id + ']';
+    const rhs = other.name + '[' + other.id + ']';
+    return swap
+      ? '[' + rhs + ' != ' + lhs + ']'
+      : '[' + lhs + ' != ' + rhs + ']';
+  }
+
+  subst (search, replace) {
+    if (search instanceof FreeVar && search.name === this.name && search.scope === this.scope)
+      return replace;
+    return null;
+  }
+
   _format (options, nargs) {
-    return options.var[0] + this.name + options.var[1];
+    const name = options.html ? this.fancyName ?? this.name : this.name;
+    return options.var[0] + name + options.var[1];
   }
 }
 
-/**
- * @typedef {function(Expr): Expr | AnyArity} AnyArity
- */
-
 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.
+   * @desc A named term with a known rewriting rule.
+   *       'impl' is a function with signature Expr => Expr => ... => Expr
+   *       (see typedef Partial).
+   *       This is how S, K, I, and company are implemented.
+   *
+   *       Note that as of current something like a=>b=>b(a) is not possible,
+   *       use full form instead: a=>b=>b.apply(a).
+   *
+   * @example new Native('K', x => y => x); // constant
+   * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
+   *
    * @param {String} name
-   * @param {AnyArity} impl
-   * @param {{note: string?, arity: number?, canonize: boolean?, apply: function(Expr):(Expr|null) }} [opt]
+   * @param {Partial} impl
+   * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
    */
   constructor (name, impl, opt = {}) {
     super(name);
     // setup essentials
-    this.impl  = impl;
-    if (opt.apply)
-      this.onApply = opt.apply;
-    this.arity = opt.arity ?? 1;
-
-    // try to bootstrap and guess some of our properties
-    const guess = (opt.canonize ?? true) ? this.guess() : { normal: false };
+    this.invoke  = impl;
 
-    if (!opt.arity)
-      this.arity = guess.arity || 1;
+    // TODO infer lazily (on demand, only once); app capabilities such as discard and duplicate
+    // try to bootstrap and infer some of our properties
+    const guess = (opt.canonize ?? true) ? this.infer() : { normal: false };
 
+    this.arity = opt.arity || guess.arity || 1;
     this.note = opt.note ?? guess.expr?.format({ terse: true, html: true, lambda: ['', ' &mapsto; ', ''] });
   }
 
-  apply (...args) {
-    if (this.onApply && args.length >= 1) {
-      if (typeof this.onApply !== 'function') {
-        throw new Error('Native combinator ' + this + ' has an invalid onApply property  of type'
-          + typeof this.onApply + ': ' + this.onApply);
-      }
-      const subst = this.onApply(args[0]);
-      if (subst instanceof Expr)
-        return subst.apply(...args.slice(1));
-    }
-    return super.apply(...args);
-  }
-
   _rski (options) {
     if (this === native.I || this === native.K || this === native.S || (options.steps >= options.max))
       return this;
-    const canon = this.guess().expr;
+    const canon = this.infer().expr;
     if (!canon)
       return this;
     options.steps++;
     return canon._rski(options);
   }
-
-  reduce (args) {
-    if (args.length < this.arity)
-      return null;
-    let egde = 0;
-    let step = this.impl;
-    while (typeof step === 'function') {
-      if (egde >= args.length)
-        return null;
-      step = step(args[egde++]);
-    }
-    if (!(step instanceof Expr))
-      throw new Error('Native combinator ' + this + ' reduced to a non-expression: ' + step);
-    return step.apply(...args.slice(egde));
-  }
 }
 
+// predefined global combinator list
+// it is required by toSKI method, otherwise it could've as well be in parse.js
+/**
+ * @type {{[key: string]: Native}}
+ */
 const native = {};
 function addNative (name, impl, opt) {
   native[name] = new Native(name, impl, opt);
@@ -785,9 +821,20 @@ function addNative (name, impl, opt) {
 
 class Lambda extends Expr {
   /**
-     * @param {FreeVar|FreeVar[]} arg
-     * @param {Expr} impl
-     */
+   * @desc Lambda abstraction of arg over impl.
+   *     Upon evaluation, all occurrences of 'arg' within 'impl' will be replaced
+   *     with the provided argument.
+   *
+   * Note that 'arg' will be replaced by a localized placeholder, so the original
+   * variable can be used elsewhere without interference.
+   * Listing symbols contained in the lambda will omit such placeholder.
+   *
+   * Legacy ([FreeVar], impl) constructor is supported but deprecated.
+   * It will create a nested lambda expression.
+   *
+   * @param {FreeVar} arg
+   * @param {Expr} impl
+   */
   constructor (arg, impl) {
     if (Array.isArray(arg)) {
       // check args before everything
@@ -811,39 +858,45 @@ class Lambda extends Expr {
 
     super();
 
-    // localize argument variable as it may appear elsewhere
-    const local = new FreeVar(arg.name);
+    // localize argument variable and bind it to oneself
+    const local = new FreeVar(arg.name, this);
     this.arg = local;
     this.impl = impl.subst(arg, local) ?? impl;
     this.arity = 1;
   }
 
-  getSymbols () {
-    const out = this.impl.getSymbols();
-    out.delete(this.arg);
-    out.set(Expr.lambdaPlaceholder, (out.get(Expr.lambdaPlaceholder) ?? 0) + 1);
-    return out;
-  }
-
   weight () {
     return this.impl.weight() + 1;
   }
 
-  _guess (options, preArgs = [], steps = 0) {
+  _infer (options, preArgs = [], steps = 0) {
     if (preArgs.length > options.maxArgs)
       return { normal: false, steps };
 
     const push = nthvar(preArgs.length + options.index);
-    return this.reduce([push])._guess(options, [...preArgs, push], steps + 1);
+    return this.invoke(push)._infer(options, [...preArgs, push], steps + 1);
   }
 
-  reduce (input) {
-    if (input.length === 0)
-      return null;
+  invoke (arg) {
+    return this.impl.subst(this.arg, arg) ?? this.impl;
+  }
+
+  traverse (change) {
+    const replaced = change(this);
+    if (replaced instanceof Expr)
+      return replaced;
 
-    const [head, ...tail] = input;
+    // alas no proper shielding of self.arg is possible
+    const impl = this.impl.traverse(change);
+
+    if (!impl)
+      return null; // no changes
+
+    return new Lambda(this.arg, impl);
+  }
 
-    return (this.impl.subst(this.arg, head) ?? this.impl).apply(...tail);
+  any (predicate) {
+    return predicate(this) || this.impl.any(predicate);
   }
 
   subst (search, replace) {
@@ -864,12 +917,12 @@ class Lambda extends Expr {
     options.steps++;
     if (impl === this.arg)
       return native.I;
-    if (!impl.getSymbols().has(this.arg))
+    if (!impl.any(e => e === this.arg))
       return native.K.apply(impl);
     if (impl instanceof App) {
       const [fst, snd] = impl.split();
       // try eta reduction
-      if (snd === this.arg && !fst.getSymbols().has(this.arg))
+      if (snd === this.arg && !fst.any(e => e === this.arg))
         return fst._rski(options);
       // fall back to S
       return native.S.apply(
@@ -880,25 +933,16 @@ class Lambda extends Expr {
     throw new Error('Don\'t know how to convert to SKI' + this);
   }
 
-  _replace (pairs, opt) {
-    const maybe = super._replace(pairs, opt);
-    if (maybe)
-      return maybe;
-    // TODO filter out terms containing this.arg
-    return new Lambda(this.arg, this.impl._replace(pairs, opt) ?? this.impl);
-  }
-
-  equals (other) {
+  diff (other, swap = false) {
     if (!(other instanceof Lambda))
-      return super.equals(other);
+      return super.diff(other, swap);
 
-    const t = new FreeVar('t');
+    const t = new FreeVar('t'); // TODO better placeholder name
 
-    return other.reduce([t]).equals(this.reduce([t]));
-  }
-
-  contains (other) {
-    return this.equals(other) || this.impl.contains(other);
+    const diff = this.invoke(t).diff(other.invoke(t), swap);
+    if (diff)
+      return '(t->' + diff + ')'; // parentheses required to avoid ambiguity
+    return null;
   }
 
   _format (options, nargs) {
@@ -920,6 +964,11 @@ class Lambda extends Expr {
 }
 
 class Church extends Native {
+  /**
+   * @desc Church numeral representing non-negative integer n:
+   *      n f x = f(f(...(f x)...)) with f applied n times.
+   * @param {number} n
+   */
   constructor (n) {
     const p = Number.parseInt(n);
     if (!(p >= 0))
@@ -938,10 +987,14 @@ class Church extends Native {
     this.arity = 2;
   }
 
-  equals (other) {
-    if (other instanceof Church)
-      return this.n === other.n;
-    return super.equals(other);
+  diff (other, swap = false) {
+    if (!(other instanceof Church))
+      return super.diff(other, swap);
+    if (this.n === other.n)
+      return null;
+    return swap
+      ? '[' + other.n + ' != ' + this.n + ']'
+      : '[' + this.n + ' != ' + other.n + ']';
   }
 
   _unspaced (arg) {
@@ -949,9 +1002,23 @@ class Church extends Native {
   }
 }
 
+function waitn (expr, n) {
+  return arg => n <= 1 ? expr.apply(arg) : waitn(expr.apply(arg), n - 1);
+}
+
 class Alias extends Named {
   /**
-   * @desc An existing expression under a different name.
+   * @desc A named alias for an existing expression.
+   *
+   *     Upon evaluation, the alias expands into the original expression,
+   *     unless it has a known arity > 0 and is marked terminal,
+   *     in which case it waits for enough arguments before expanding.
+   *
+   *     A hidden mutable property 'outdated' is used to silently
+   *     replace the alias with its definition in all contexts.
+   *     This is used when declaring named terms in an interpreter,
+   *     to avoid confusion between old and new terms with the same name.
+   *
    * @param {String} name
    * @param {Expr} impl
    * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
@@ -964,16 +1031,13 @@ class Alias extends Named {
       this.note = options.note;
 
     const guess = options.canonize
-      ? impl.guess({ max: options.max, maxArgs: options.maxArgs })
+      ? impl.infer({ max: options.max, maxArgs: options.maxArgs })
       : { normal: false };
     this.arity = (guess.proper && guess.arity) || 0;
     this.proper = guess.proper ?? false;
     this.terminal = options.terminal ?? this.proper;
     this.canonical = guess.expr;
-  }
-
-  getSymbols () {
-    return this.terminal ? new Map([[this, 1]]) : this.impl.getSymbols();
+    this.invoke = waitn(impl, this.arity);
   }
 
   weight () {
@@ -984,14 +1048,22 @@ class Alias extends Named {
     return this.impl.expand();
   }
 
+  traverse (change) {
+    return change(this) ?? this.impl.traverse(change);
+  }
+
+  any (predicate) {
+    return predicate(this) || this.impl.any(predicate);
+  }
+
   subst (search, replace) {
     if (this === search)
       return replace;
     return this.impl.subst(search, replace);
   }
 
-  _guess (options, preArgs = [], steps = 0) {
-    return this.impl._guess(options, preArgs, steps);
+  _infer (options, preArgs = [], steps = 0) {
+    return this.impl._infer(options, preArgs, steps);
   }
 
   /**
@@ -1006,22 +1078,14 @@ class Alias extends Named {
     return { expr: this.impl, steps: 0, changed: true };
   }
 
-  reduce (args) {
-    if (args.length < this.arity)
-      return null;
-    return this.impl.apply(...args);
-  }
-
   _firstVar () {
     return this.impl._firstVar();
   }
 
-  equals (other) {
-    return other.equals(this.impl);
-  }
-
-  contains (other) {
-    return this.impl.contains(other);
+  diff (other, swap = false) {
+    if (this === other)
+      return null;
+    return other.diff(this.impl, !swap);
   }
 
   _rski (options) {
@@ -1040,6 +1104,7 @@ class Alias extends Named {
   }
 
   _declare (output, inventory, seen) {
+    // this is part of the 'declare' function, see below
     // only once
     if (seen.has(this))
       return;
@@ -1064,20 +1129,15 @@ addNative('B', x => y => z => x.apply(y.apply(z)));
 addNative('C', x => y => z => x.apply(z).apply(y));
 addNative('W', x => y => x.apply(y).apply(y));
 
-addNative('+', x => y => z => y.apply(x.apply(y, z)), {
-  note:  '<var>n</var> &mapsto; <var>n</var> + 1 <i>or</i> SB',
-  apply: arg => arg instanceof Church ? new Church(arg.n + 1) : null
-});
-
-// A global value meaning "lambda is used somewhere in this expression"
-// Can't be used (at least for now) to construct lambda expressions, or anything at all.
-// See also getSymbols().
-Expr.lambdaPlaceholder = new Native('->', x => x, {
-  arity:    1,
-  canonize: false,
-  note:     'Lambda placeholder',
-  apply:    x => { throw new Error('Attempt to use a placeholder in expression') }
-});
+addNative(
+  '+',
+  n => n instanceof Church
+    ? new Church(n.n + 1)
+    : f => x => f.apply(n.apply(f, x)),
+  {
+    note: 'Increase a Church numeral argument by 1, otherwise n => f => x => f(n f x)',
+  }
+);
 
 // utility functions dependent on Expr* classes, in alphabetical order
 
@@ -1136,9 +1196,28 @@ function declare (inventory) {
 }
 
 function maybeLambda (args, expr, caps = {}) {
-  const sym = expr.getSymbols();
+  const count = new Array(args.length).fill(0);
+  let proper = true;
+  expr.traverse(e => {
+    if (e instanceof FreeVar) {
+      const index = args.findIndex(a => a.name === e.name);
+      if (index >= 0) {
+        count[index]++;
+        return;
+      }
+    }
+    if (!(e instanceof App))
+      proper = false;
+  });
 
-  const [skip, dup] = skipDup(args, sym);
+  const skip = new Set();
+  const dup = new Set();
+  for (let i = 0; i < args.length; i++) {
+    if (count[i] === 0)
+      skip.add(i);
+    else if (count[i] > 1)
+      dup.add(i);
+  }
 
   return {
     expr:      args.length ? new Lambda(args, expr) : expr,
@@ -1147,7 +1226,7 @@ function maybeLambda (args, expr, caps = {}) {
     ...(dup.size ? { dup } : {}),
     duplicate: !!dup.size  || caps.duplicate || false,
     discard:   !!skip.size || caps.discard   || false,
-    proper:    isSubset(sym.keys(), new Set(args)),
+    proper,
   };
 }
 
@@ -1161,7 +1240,7 @@ function naiveCanonize (expr) {
   if (expr instanceof Alias)
     return naiveCanonize(expr.impl);
 
-  const canon = expr.guess();
+  const canon = expr.infer();
   if (canon.expr)
     return canon.expr;
 
@@ -1225,10 +1304,13 @@ function * simplifyLambda (expr, options = {}, state = { steps: 0 }) {
     }
   }
 
-  const canon = expr.guess({ max: options.max, maxArgs: options.maxArgs });
+  const canon = expr.infer({ max: options.max, maxArgs: options.maxArgs });
   state.steps += canon.steps;
   if (canon.expr && canon.expr.weight() < maxWeight)
     yield { expr: canon.expr, steps: state.steps, comment: '(canonical)' };
 }
 
-module.exports = { Expr, App, FreeVar, Lambda, Native, Alias, Church, globalOptions, native, declare };
+Expr.declare = declare;
+Expr.native = native;
+
+module.exports = { Expr, App, FreeVar, Lambda, Native, Alias, Church };