@dallaylaen/ski-interpreter 1.3.0 → 2.1.0

package/lib/expr.js

@@ -1,20 +1,40 @@
 'use strict';
 
-const { skipDup, isSubset } = require('./util');
+const { unwrap, prepareWrapper } = require('./internal');
 
-const globalOptions = {
-  terse:   true,
+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)
@@ -22,107 +42,86 @@ 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;
+    let expr = this;
+    for (const arg of args)
+      expr = new App(expr, arg);
+    return expr;
   }
 
   /**
-     * 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 () {
+    return !this.any(e => !(e instanceof FreeVar || e instanceof App));
   }
 
-  freeOnly () {
-    for (const [key, _] of this.getSymbols()) {
-      if (!(key instanceof FreeVar))
-        return false;
-    }
-    return true;
+  /**
+   * @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}
+   */
+  traverse (change) {
+    return change(this);
   }
 
   /**
-   * @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 Returns true if predicate() is true for any subterm of the expression, false otherwise.
+   *
+   * @param {(e: Expr) => boolean} predicate
+   * @returns {boolean}
    */
-  getSymbols () {
-    // TODO better name!
-    return new Map([[this, 1]]);
+  any (predicate) {
+    return predicate(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.
+   * @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.
    *
-   *   @example  S(SKK)(SKS).replace('I') = SII // we found 2 subtrees equivalent to I
-   *             and replaced them with I
+   * null or undefined return value from combine() means "keep current value and descend further".
    *
-   *   @param {(Expr | [find: Expr, replace: Expr])[]} terms
-   *   @param {Object} [opt] - options
-   *   @return {Expr}
+   * 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}
    */
-  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;
+
+  fold (initial, combine) {
+    const [value, _] = unwrap(this._fold(initial, combine));
+    return value ?? initial;
   }
 
-  _replace (pairs, opt) {
-    const check = this.guess(opt).expr;
-    for (const [canon, term] of pairs) {
-      if (check.equals(canon))
-        return term;
-    }
-    return null;
+  _fold (initial, combine) {
+    return combine(initial, this);
   }
 
   /**
-   * @desc rought estimate of the complexity of the term
+   * @desc rough estimate of the complexity of the term
    * @return {number}
    */
   weight () {
@@ -130,18 +129,18 @@ 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
+   * @param {{max?: number, maxArgs?: number}} options
    * @return {{
    *    normal: boolean,
    *    steps: number,
@@ -154,14 +153,22 @@ 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) {
+  /**
+   *
+   * @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 };
 
@@ -182,29 +189,45 @@ 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);
 
-    if (this._firstVar())
+    // 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.unroll()[0] instanceof FreeVar)
       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 () {
+  /**
+   * @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
-    // used by guess()
-    return false;
-  }
-
   /**
    * @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,
@@ -216,17 +239,29 @@ class Expr {
    * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
    * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
    */
-  * lambdify (options = {}) {
-    const expr = naiveCanonize(this, options);
+  * toLambda (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);
   }
 
   /**
-   * @desc same semantics as walk() but rewrite step by step instead of computing
-   * @param {{max: number?}} options
+   * @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,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;
   }
@@ -252,7 +293,7 @@ class Expr {
    * 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}
@@ -285,19 +326,19 @@ class Expr {
   }
 
   /**
-     * @desc iterate one step of a calculation.
-     * @return {{expr: Expr, steps: number, changed: boolean}}
-     */
+   * @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);
@@ -306,7 +347,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();
@@ -323,11 +364,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;
@@ -350,20 +391,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 + ']';
   }
 
   /**
@@ -375,12 +445,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;
@@ -404,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);
   }
@@ -416,10 +493,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
@@ -440,9 +518,8 @@ class Expr {
    * @example foo.format({ inventory: { T } }) // use T as a named term, expand all others
    *
    */
-
   format (options = {}) {
-    const defaults = options.html
+    const fallback = options.html
       ? {
         brackets: ['(', ')'],
         space:    ' ',
@@ -460,39 +537,49 @@ 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);
   }
 
+  /**
+   * @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;
   }
@@ -501,30 +588,23 @@ 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
 
-    const [first, ...list] = this._aslist();
+    const [first, ...list] = this.unroll();
     if (!(first instanceof FreeVar))
       return { normal: false, steps }
     // TODO maybe do it later
@@ -533,7 +613,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,
@@ -550,27 +630,48 @@ 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());
   }
 
-  _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);
+  }
+
+  _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) {
@@ -627,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];
   }
 
   /**
@@ -647,15 +743,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) {
@@ -685,9 +783,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)
@@ -705,30 +804,64 @@ 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 () {
     return 0;
   }
 
-  _firstVar () {
-    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];
   }
 }
 
@@ -754,9 +887,9 @@ class Native extends Named {
     // setup essentials
     this.invoke  = impl;
 
-    // TODO guess lazily (on demand, only once); app capabilities such as discard and duplicate
-    // try to bootstrap and guess some of our properties
-    const guess = (opt.canonize ?? true) ? this.guess() : { normal: false };
+    // 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; ', ''] });
@@ -765,7 +898,7 @@ class Native extends Named {
   _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++;
@@ -773,6 +906,11 @@ class Native extends Named {
   }
 }
 
+// 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);
@@ -817,36 +955,59 @@ 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.invoke(push)._guess(options, [...preArgs, push], steps + 1);
+    return this.invoke(push)._infer(options, [...preArgs, push], steps + 1);
   }
 
   invoke (arg) {
     return this.impl.subst(this.arg, arg) ?? this.impl;
   }
 
+  traverse (change) {
+    const replaced = change(this);
+    if (replaced instanceof Expr)
+      return replaced;
+
+    // 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);
+  }
+
+  any (predicate) {
+    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;
@@ -865,41 +1026,32 @@ 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();
+      const { fun, arg } = impl;
       // try eta reduction
-      if (snd === this.arg && !fst.getSymbols().has(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);
   }
 
-  _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);
-
-    const t = new FreeVar('t');
+      return super.diff(other, swap);
 
-    return other.invoke(t).equals(this.invoke(t));
-  }
+    const t = new FreeVar('t'); // TODO better placeholder name
 
-  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) {
@@ -944,10 +1096,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) {
@@ -984,7 +1140,7 @@ 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;
@@ -993,10 +1149,6 @@ class Alias extends Named {
     this.invoke = waitn(impl, this.arity);
   }
 
-  getSymbols () {
-    return this.terminal ? new Map([[this, 1]]) : this.impl.getSymbols();
-  }
-
   weight () {
     return this.terminal ? 1 : this.impl.weight();
   }
@@ -1005,14 +1157,34 @@ 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);
+  }
+
+  _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;
     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);
   }
 
   /**
@@ -1027,16 +1199,10 @@ class Alias extends Named {
     return { expr: this.impl, steps: 0, changed: true };
   }
 
-  _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) {
@@ -1090,16 +1256,6 @@ addNative(
   }
 );
 
-// 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') }
-});
-
 // utility functions dependent on Expr* classes, in alphabetical order
 
 /**
@@ -1157,9 +1313,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,
@@ -1168,27 +1343,10 @@ 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,
   };
 }
 
-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.guess();
-  if (canon.expr)
-    return canon.expr;
-
-  throw new Error('Failed to canonize expression: ' + expr);
-}
-
 function nthvar (n) {
   return new FreeVar('abcdefgh'[n] ?? 'x' + n);
 }
@@ -1226,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);
@@ -1246,10 +1404,14 @@ 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;
+Expr.control = control;
+
+module.exports = { Expr, App, Named, FreeVar, Lambda, Native, Alias, Church };