@dallaylaen/ski-interpreter 1.1.0 → 1.3.0

package/lib/expr.js

@@ -8,6 +8,10 @@ const globalOptions = {
   maxArgs: 32,
 };
 
+/**
+ * @typedef {Expr | function(Expr): Partial} Partial
+ */
+
 class Expr {
   /**
    *  @descr A generic combinatory logic expression.
@@ -141,13 +145,13 @@ class Expr {
    * @return {{
    *    normal: boolean,
    *    steps: number,
-   *    expr: Expr?,
-   *    arity: number?,
-   *    proper: boolean?,
-   *    discard: boolean?,
-   *    duplicate: boolean?,
-   *    skip: Set<number>?,
-   *    dup: Set<number>?
+   *    expr?: Expr,
+   *    arity?: number,
+   *    proper?: boolean,
+   *    discard?: boolean,
+   *    duplicate?: boolean,
+   *    skip?: Set<number>,
+   *    dup?: Set<number>,
    * }}
    */
   guess (options = {}) {
@@ -202,12 +206,12 @@ class Expr {
    *       up to the provided computation steps limit,
    *       in decreasing weight order.
    * @param {{
-   *   max: number?,
-   *   maxArgs: number?,
-   *   varGen: function(void): FreeVar?,
-   *   steps: number?,
-   *   html: boolean?,
-   *   latin: number?,
+   *   max?: number,
+   *   maxArgs?: number,
+   *   varGen?: function(void): FreeVar,
+   *   steps?: number,
+   *   html?: boolean,
+   *   latin?: number,
    * }} options
    * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
    * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
@@ -238,44 +242,50 @@ class Expr {
     }
   }
 
-  /**
-   * @desc Rename free variables in the expression using the given sequence
-   *       This is for eye-candy only, as the interpreter knows darn well hot to distinguish vars,
-   *       regardless of names.
-   * @param {IterableIterator<string>} seq
-   * @return {Expr}
-   */
-  renameVars (seq) {
-    return this;
-  }
-
   _rski (options) {
     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().
+   * @param {Expr} search
+   * @param {Expr} replace
+   * @return {Expr|null}
+   */
+  subst (search, replace) {
+    return this === search ? replace : null;
   }
 
   /**
-     * Replace all instances of free vars with corresponding values and return the resulting expression.
-     * return null if no changes could be made.
-     * @param {FreeVar} plug
-     * @param {Expr} value
-     * @return {Expr|null}
-     */
-  subst (plug, value) {
+   * @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 calculation in accordance with known rules.
+     * @desc iterate one step of a calculation.
      * @return {{expr: Expr, steps: number, changed: boolean}}
      */
   step () { return { expr: this, steps: 0, changed: false } }
@@ -371,19 +381,18 @@ class Expr {
     // 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);
-    poorMans.expected = expected.toString();
-    poorMans.actual = this.toString();
+    poorMans.expected = expected + '';
+    poorMans.actual = this + '';
     throw poorMans;
   }
 
   /**
-   * @param {{terse: boolean?, html: boolean?}} [options]
-   * @return {string} string representation of the expression
+   * @desc Returns string representation of the expression.
+   *       Same as format() without options.
+   * @return {string}
    */
-  toString (options = {}) {
-    // uncomment the following line if you want to debug the parser with prints
-    // return this.constructor.name
-    throw new Error( 'No toString() method defined in class ' + this.constructor.name );
+  toString () {
+    return this.format();
   }
 
   /**
@@ -391,17 +400,83 @@ class Expr {
    * @param {boolean} [first] - whether this is the first term in a sequence
    * @return {boolean}
    */
-  needsParens (first) {
+  _braced (first) {
     return false;
   }
 
+  _unspaced (arg) {
+    return this._braced(true);
+  }
+
   /**
+   * @desc    Stringify the expression with fancy formatting options.
+   *          Said options mostly include wrappers around various constructs in form of ['(', ')'],
+   *          as well as terse and html flags that set up the defaults.
+   *          Format without options is equivalent to toString() and can be parsed back.
+   *
+   * @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   {[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)
+   * @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
+   * @param   {[string, string]} [options.around]    - wrappers around (sub-)expressions.
+   *                                individual applications will not be wrapped, i.e. (a b c) but not ((a b) c)
+   * @param   {[string, string]} [options.redex]     - wrappers around the starting term(s) that have enough arguments to be reduced
+   * @param   {Object<string, Expr>} [options.inventory]     - if given, output aliases in the set as their names
+   *                                and any other aliases as the expansion of their definitions.
+   *                                The default is a cryptic and fragile mechanism dependent on a hidden mutable property.
+   * @returns {string}
+   *
+   * @example foo.format() // equivalent to foo.toString()
+   * @example foo.format({terse: false}) // spell out all parentheses
+   * @example foo.format({html: true}) // use HTML tags and entities
+   * @example foo.format({ around: ['(', ')'], brackets: ['', ''], lambda: ['(', '->', ')'] }) // lisp style, still back-parsable
+   * @exapmle foo.format({ lambda: ['&lambda;', '.', ''] }) // pretty-print for the math department
+   * @example foo.format({ lambda: ['', '=>', ''], terse: false }) // make it javascript
+   * @example foo.format({ inventory: { T } }) // use T as a named term, expand all others
    *
-   * @return {string}
    */
-  toJSON () {
-    return this.expand().toString({ terse: false });
+
+  format (options = {}) {
+    const defaults = options.html
+      ? {
+        brackets: ['(', ')'],
+        space:    ' ',
+        var:      ['<var>', '</var>'],
+        lambda:   ['', '-&gt;', ''],
+        around:   ['', ''],
+        redex:    ['', ''],
+      }
+      : {
+        brackets: ['(', ')'],
+        space:    ' ',
+        var:      ['', ''],
+        lambda:   ['', '->', ''],
+        around:   ['', ''],
+        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,
+      inventory: options.inventory, // TODO better name
+    }, 0);
+  }
+
+  _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) {}
 }
 
 class App extends Expr {
@@ -486,12 +561,6 @@ 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());
   }
@@ -504,13 +573,9 @@ class App extends Expr {
     return (fun._replace(pairs, opt) ?? fun).apply(arg._replace(pairs, opt) ?? arg);
   }
 
-  renameVars (seq) {
-    return this.fun.renameVars(seq).apply(this.arg.renameVars(seq));
-  }
-
-  subst (plug, value) {
-    const fun = this.fun.subst(plug, value);
-    const arg = this.arg.subst(plug, value);
+  subst (search, replace) {
+    const fun = this.fun.subst(search, replace);
+    const arg = this.arg.subst(search, replace);
 
     return (fun || arg) ? (fun ?? this.fun).apply(arg ?? this.arg) : null;
   }
@@ -522,34 +587,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];
   }
 
@@ -579,25 +658,28 @@ class App extends Expr {
     return this.fun.contains(other) || this.arg.contains(other) || super.contains(other);
   }
 
-  needsParens (first) {
+  _braced (first) {
     return !first;
   }
 
-  toString (opt = {}) {
-    const fun = this.fun.toString(opt);
-    const root = this.fun.needsParens(true) ? '(' + fun + ')' : fun;
-    if (opt.terse ?? globalOptions.terse) {
-      // terse mode: omit whitespace and parens if possible
-      let arg = this.arg.toString(opt);
-      if (this.arg.needsParens(false))
-        arg = '(' + arg + ')';
-      const space = (root.match(/\)$/) || arg.match(/^\(/))
-        || (root.match(/[A-Z]$/) && arg.match(/^[a-z]/i))
-        ? ''
-        : ' ';
-      return root + space + arg;
-    } else
-      return root + '(' + this.arg.toString(opt) + ')';
+  _format (options, nargs) {
+    const fun = this.fun._format(options, nargs + 1);
+    const arg = this.arg._format(options, 0);
+    const wrap = nargs ? ['', ''] : options.around;
+    // TODO ignore terse for now
+    if (options.terse && !this.arg._braced(false))
+      return wrap[0] + fun + (this.fun._unspaced(this.arg) ? '' : options.space) + arg + wrap[1];
+    else
+      return wrap[0] + fun + options.brackets[0] + arg + options.brackets[1] + wrap[1];
+  }
+
+  _declare (output, inventory, seen) {
+    this.fun._declare(output, inventory, seen);
+    this.arg._declare(output, inventory, seen);
+  }
+
+  _unspaced (arg) {
+    return this.arg._braced(false) ? true : this.arg._unspaced(arg);
   }
 }
 
@@ -613,8 +695,19 @@ class Named extends Expr {
     this.name = name;
   }
 
-  toString () {
-    return this.name;
+  _unspaced (arg) {
+    return !!(
+      (arg instanceof Named) && (
+        (this.name.match(/^[A-Z+]$/) && arg.name.match(/^[a-z+]/i))
+          || (this.name.match(/^[a-z+]/i) && arg.name.match(/^[A-Z+]$/))
+      )
+    );
+  }
+
+  _format (options, nargs) {
+    return this.arity > 0 && this.arity <= nargs
+      ? options.redex[0] + this.name + options.redex[1]
+      : this.name;
   }
 }
 
@@ -626,12 +719,6 @@ class FreeVar extends Named {
     this.id = ++freeId;
   }
 
-  subst (plug, value) {
-    if (this === plug)
-      return value;
-    return null;
-  }
-
   weight () {
     return 0;
   }
@@ -640,54 +727,39 @@ class FreeVar extends Named {
     return true;
   }
 
-  toString ( opt = {} ) {
-    return (opt.html && /^[a-z]$/.test(this.name)) ? '<var>' + this.name + '</var>' : this.name;
+  _format (options, nargs) {
+    return options.var[0] + this.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;
+    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 };
 
-    if (!opt.arity)
-      this.arity = guess.arity || 1;
-
-    this.note = opt.note ?? guess.expr?.toString({ terse: true, html: true });
-  }
-
-  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);
+    this.arity = opt.arity || guess.arity || 1;
+    this.note = opt.note ?? guess.expr?.format({ terse: true, html: true, lambda: ['', ' &mapsto; ', ''] });
   }
 
   _rski (options) {
@@ -699,25 +771,6 @@ class Native extends Named {
     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));
-  }
-
-  toJSON () {
-    return 'Native:' + this.name;
-  }
 }
 
 const native = {};
@@ -727,9 +780,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
@@ -776,37 +840,24 @@ class Lambda extends Expr {
       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)._guess(options, [...preArgs, push], steps + 1);
   }
 
-  reduce (input) {
-    if (input.length === 0)
-      return null;
-
-    const [head, ...tail] = input;
-
-    return (this.impl.subst(this.arg, head) ?? this.impl).apply(...tail);
+  invoke (arg) {
+    return this.impl.subst(this.arg, arg) ?? this.impl;
   }
 
-  subst (plug, value) {
-    if (plug === this.arg)
+  subst (search, replace) {
+    if (search === this.arg)
       return null;
-    const change = this.impl.subst(plug, value);
-    if (change)
-      return new Lambda(this.arg, change);
-    return null;
+    const change = this.impl.subst(search, replace);
+    return change ? new Lambda(this.arg, change) : null;
   }
 
   expand () {
     return new Lambda(this.arg, this.impl.expand());
   }
 
-  renameVars (seq) {
-    const arg = new FreeVar(seq.next().value);
-    const impl = this.impl.subst(this.arg, arg) ?? this.impl;
-    return new Lambda(arg, impl.renameVars(seq));
-  }
-
   _rski (options) {
     const impl = this.impl._rski(options);
     if (options.steps >= options.max)
@@ -844,24 +895,37 @@ class Lambda extends Expr {
 
     const t = new FreeVar('t');
 
-    return other.reduce([t]).equals(this.reduce([t]));
+    return other.invoke(t).equals(this.invoke(t));
   }
 
   contains (other) {
     return this.equals(other) || this.impl.contains(other);
   }
 
-  toString (opt = {}) {
-    const mapsto = opt.html ? ' &mapsto; ' : '->';
-    return this.arg.toString(opt) + mapsto + this.impl.toString(opt);
+  _format (options, nargs) {
+    return (nargs > 0 ? options.brackets[0] : '')
+      + options.lambda[0]
+      + this.arg._format(options, 0) // TODO highlight redex if nargs > 0
+      + options.lambda[1]
+      + this.impl._format(options, 0) + options.lambda[2]
+      + (nargs > 0 ? options.brackets[1] : '');
   }
 
-  needsParens (first) {
+  _declare (output, inventory, seen) {
+    this.impl._declare(output, inventory, seen);
+  }
+
+  _braced (first) {
     return true;
   }
 }
 
 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))
@@ -885,11 +949,29 @@ class Church extends Native {
       return this.n === other.n;
     return super.equals(other);
   }
+
+  _unspaced (arg) {
+    return false;
+  }
+}
+
+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]
@@ -908,6 +990,7 @@ class Alias extends Named {
     this.proper = guess.proper ?? false;
     this.terminal = options.terminal ?? this.proper;
     this.canonical = guess.expr;
+    this.invoke = waitn(impl, this.arity);
   }
 
   getSymbols () {
@@ -922,8 +1005,10 @@ class Alias extends Named {
     return this.impl.expand();
   }
 
-  subst (plug, value) {
-    return this.impl.subst(plug, value);
+  subst (search, replace) {
+    if (this === search)
+      return replace;
+    return this.impl.subst(search, replace);
   }
 
   _guess (options, preArgs = [], steps = 0) {
@@ -942,12 +1027,6 @@ 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();
   }
@@ -964,15 +1043,35 @@ class Alias extends Named {
     return this.impl._rski(options);
   }
 
-  toString (opt) {
-    return this.outdated ? this.impl.toString(opt) : super.toString(opt);
+  _braced (first) {
+    return this.outdated ? this.impl._braced(first) : false;
+  }
+
+  _format (options, nargs) {
+    const outdated = options.inventory
+      ? options.inventory[this.name] !== this
+      : this.outdated;
+    return outdated ? this.impl._format(options, nargs) : super._format(options, nargs);
   }
 
-  needsParens (first) {
-    return this.outdated ? this.impl.needsParens() : false;
+  _declare (output, inventory, seen) {
+    // this is part of the 'declare' function, see below
+    // only once
+    if (seen.has(this))
+      return;
+    seen.add(this);
+
+    // topological order
+    this.impl._declare(output, inventory, seen);
+
+    // only declare if in inventory and matches
+    if (inventory[this.name] === this)
+      output.push(this.name + '=' + this.impl.format({ terse: true, inventory }));
   }
 }
 
+// ----- Expr* classes end here -----
+
 // declare native combinators
 addNative('I', x => x);
 addNative('K', x => _ => x);
@@ -981,11 +1080,82 @@ 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
+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)',
+  }
+);
+
+// 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
+
+/**
+ *
+ * @param {Expr[]} inventory
+ * @return {string[]}
+ */
+function declare (inventory) {
+  const misnamed = Object.keys(inventory)
+    .filter(s => !(inventory[s] instanceof Named && inventory[s].name === s))
+    .map(s => s + ' = ' + inventory[s]);
+  if (misnamed.length > 0)
+    throw new Error('Inventory must be a hash of named terms with matching names: ' + misnamed.join(', '));
+
+  inventory = { ...inventory }; // shallow copy to avoid mutating input
+
+  // If any aliases mask native terms, those cannot be easily restored.
+  // Moreover, subsequent terms may refer to both native term and and the conflicting alias.
+  // Therefore, we will instead rename such aliases to something else
+  // and only restore them at the end.
+  const detour = [];
+  let tmpId = 1;
+  for (const name in native) {
+    if (!(inventory[name] instanceof Alias))
+      continue;
+    while ('temp' + tmpId in inventory)
+      tmpId++;
+    const temp = 'temp' + tmpId;
+    const orig = inventory[name];
+    delete inventory[name];
+    const masked = new Alias(temp, orig);
+    for (const key in inventory)
+      inventory[key] = inventory[key].subst(orig, masked) ?? inventory[key];
+
+    inventory[temp] = masked;
+    detour.push([name, temp]);
+  }
+
+  // only want to declare aliases
+  const terms = Object.values(inventory)
+    .filter(s => s instanceof Alias)
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const out = [];
+  const seen = new Set();
+  for (const term of terms)
+    term._declare(out, inventory, seen);
+
+  for (const [name, temp] of detour) {
+    out.push(name + '=' + temp); // rename
+    out.push(temp + '=');        // delete
+  }
+
+  return out;
+}
+
 function maybeLambda (args, expr, caps = {}) {
   const sym = expr.getSymbols();
 
@@ -1019,6 +1189,10 @@ function naiveCanonize (expr) {
   throw new Error('Failed to canonize expression: ' + expr);
 }
 
+function nthvar (n) {
+  return new FreeVar('abcdefgh'[n] ?? 'x' + n);
+}
+
 /**
  *
  * @param {Expr} expr
@@ -1078,18 +1252,4 @@ function * simplifyLambda (expr, options = {}, state = { steps: 0 }) {
     yield { expr: canon.expr, steps: state.steps, comment: '(canonical)' };
 }
 
-function nthvar (n) {
-  return new FreeVar('abcdefgh'[n] ?? 'x' + n);
-}
-
-// 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') }
-});
-
-module.exports = { Expr, App, FreeVar, Lambda, Native, Alias, Church, globalOptions, native };
+module.exports = { Expr, App, FreeVar, Lambda, Native, Alias, Church, globalOptions, native, declare };