@dallaylaen/ski-interpreter 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-12-14
+
+### BREAKING CHANGES
+
+- Remove `toString()` options, use `format()` instead.
+- Make `needsParens()` private (should've been to begin with)
+- Remove unused `renameVars()` method.
+- Remove Expr.`toJSON()`
+
+### Added
+
+- SKI: `toJSON()` now recreates declarations exactly, preserving named subexpressions.
+- SKI: `declare()` / `bulkAdd()` methods to export/import term definitions.
+- Expr: `format(options?)` method for pretty-printing expressions with various options: html, verbosity, custom lambdas, custom brackets etc.
+- Expr: `subst(find, replace)` now works for any type of find  except application and lambdas.
+- Playground: permalinks now use #hash instead of a ?query string. (Old links still supported).
+- Playground: togglable frames around subexpressions & variable/redex highlighting.
+
 ## [1.1.0] - 2025-12-07
 
 ### BREAKING CHANGES
@@ -21,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Expr: guess() method to normalize terms.
   Returns an object with `normal`: boolean and `steps`:
   number properties, as well as optional `expr`: Expr -
-  equivalent lambda expression; `arity`: number, 
+  equivalent lambda expression; `arity`: number,
   and other properties.
 - Expr: replace(terms: Expr[], options: {}) replaces
   subtrees with matching canonical form (if they have one).

package/bin/ski.js

@@ -69,7 +69,7 @@ function runLine(onErr) {
                 if (state.final && !options.q)
                     console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
                 if (options.v || state.final)
-                    console.log('' + state.expr.toString({terse: options.t}));
+                    console.log('' + state.expr.format({terse: options.t}));
                 if (state.final && expr instanceof SKI.classes.Alias)
                     ski.add(expr.name, state.expr);
             }

package/lib/expr.js

@@ -141,13 +141,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 +202,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,17 +238,6 @@ 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;
   }
@@ -264,14 +253,18 @@ class Expr {
   }
 
   /**
-     * 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) {
-    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;
   }
 
   /**
@@ -371,19 +364,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 +383,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:    ['<b>', '</b>'],
+      }
+      : {
+        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 {
@@ -504,13 +562,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;
   }
@@ -579,25 +633,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 +670,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 +694,6 @@ class FreeVar extends Named {
     this.id = ++freeId;
   }
 
-  subst (plug, value) {
-    if (this === plug)
-      return value;
-    return null;
-  }
-
   weight () {
     return 0;
   }
@@ -640,8 +702,8 @@ 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];
   }
 }
 
@@ -674,7 +736,7 @@ class Native extends Named {
     if (!opt.arity)
       this.arity = guess.arity || 1;
 
-    this.note = opt.note ?? guess.expr?.toString({ terse: true, html: true });
+    this.note = opt.note ?? guess.expr?.format({ terse: true, html: true, lambda: ['', ' &mapsto; ', ''] });
   }
 
   apply (...args) {
@@ -714,10 +776,6 @@ class Native extends Named {
       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 = {};
@@ -788,25 +846,17 @@ class Lambda extends Expr {
     return (this.impl.subst(this.arg, head) ?? this.impl).apply(...tail);
   }
 
-  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)
@@ -851,12 +901,20 @@ class Lambda extends Expr {
     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;
   }
 }
@@ -885,6 +943,10 @@ class Church extends Native {
       return this.n === other.n;
     return super.equals(other);
   }
+
+  _unspaced (arg) {
+    return false;
+  }
 }
 
 class Alias extends Named {
@@ -922,8 +984,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) {
@@ -964,15 +1028,34 @@ 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;
   }
 
-  needsParens (first) {
-    return this.outdated ? this.impl.needsParens() : 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);
+  }
+
+  _declare (output, inventory, seen) {
+    // 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);
@@ -986,6 +1069,72 @@ addNative('+', x => y => z => y.apply(x.apply(y, z)), {
   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') }
+});
+
+// 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 +1168,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 +1231,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 };

package/lib/parser.js

@@ -3,7 +3,7 @@
  */
 
 const { Tokenizer, restrict } = require('./util');
-const { globalOptions, Expr, App, FreeVar, Lambda, Native, Alias, Church, native } = require('./expr');
+const { globalOptions, Expr, App, FreeVar, Lambda, Native, Alias, Church, native, declare } = require('./expr');
 
 class Empty extends Expr {
   apply (...args) {
@@ -55,11 +55,11 @@ class SKI {
   /**
    *
    * @param {{
-   *    allow: string?,
-   *    numbers: boolean?,
-   *    lambdas: boolean?,
-   *    terms: { [key: string]: Expr|string}?,
-   *    annotate: boolean?,
+   *    allow?: string,
+   *    numbers?: boolean,
+   *    lambdas?: boolean,
+   *    terms?: { [key: string]: Expr|string} | string[],
+   *    annotate?: boolean,
    * }} [options]
    */
   constructor (options = {}) {
@@ -70,10 +70,14 @@ class SKI {
     this.allow = new Set(Object.keys(this.known));
 
     // Import terms, if any. Omit native ones
-    for (const name in options.terms ?? {}) {
-      // Native terms already handled by allow
-      if (!options.terms[name].match(/^Native:/))
-        this.add(name, options.terms[name]);
+    if (Array.isArray(options.terms))
+      this.bulkAdd(options.terms);
+    else if (options.terms) {
+      for (const name in options.terms) {
+        // Native terms already handled by allow
+        if (!options.terms[name].match(/^Native:/))
+          this.add(name, options.terms[name]);
+      }
     }
 
     // Finally, impose restrictions
@@ -107,12 +111,14 @@ class SKI {
       throw new Error('add: term must be an Alias or a string (accompanied with an implementation)');
 
     if (this.annotate && note === undefined && term.canonical)
-      note = term.canonical.toString({ terse: true, html: true });
+      note = term.canonical.format({ terse: true, html: true, lambda: ['', ' ↦ ', ''] });
     if (note !== undefined)
       term.note = note;
 
-    this.known['' + term] = term;
-    this.allow.add('' + term);
+    if (this.known[term.name])
+      this.known[term.name].outdated = true;
+    this.known[term.name] = term;
+    this.allow.add(term.name);
 
     return this;
   }
@@ -125,6 +131,28 @@ class SKI {
     return this;
   }
 
+  /**
+   * @desc Declare and remove multiple terms at once
+   *       term=impl adds term
+   *       term= removes term
+   * @param {string[]]} list
+   * @return {SKI} chainable
+   */
+  bulkAdd (list) {
+    for (const item of list) {
+      const m = item.match(/^([A-Z]|[a-z][a-z_0-9]*)\s*=\s*(.*)$/s);
+      // TODO check all declarations before applying any (but we might need earlier terms for parsing later ones)
+      if (!m)
+        throw new Error('bulkAdd: invalid declaration: ' + item);
+      if (m[2] === '')
+        this.remove(m[1]);
+      else
+        this.add(m[1], this.parse(m[2]));
+    }
+
+    return this;
+  }
+
   /**
    * Restrict the interpreter to given terms. Terms prepended with '+' will be added
    * and terms preceeded with '-' will be removed.
@@ -183,6 +211,15 @@ class SKI {
     return out;
   }
 
+  /**
+   * Export term declarations for use in bulkAdd().
+   * @returns {string[]}
+   */
+  declare () {
+    // TODO accept argument to declare specific terms only
+    return declare(this.getTerms());
+  }
+
   /**
    *
    * @param {string} source
@@ -290,11 +327,12 @@ class SKI {
 
   toJSON () {
     return {
+      version:  '1.1.1', // set to incremented package.json version whenever SKI serialization changes
       allow:    this.showRestrict('+'),
       numbers:  this.hasNumbers,
       lambdas:  this.hasLambdas,
-      terms:    this.getTerms(),
       annotate: this.annotate,
+      terms:    this.declare(),
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter. Supports SKI, BCKW, Church numerals, and setting up assertions ('quests') involving all of the above.",
   "keywords": [
     "combinatory logic",

package/types/lib/expr.d.ts

@@ -65,13 +65,13 @@ export 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?: {
@@ -80,13 +80,13 @@ export class Expr {
     }): {
         normal: boolean;
         steps: number;
-        expr: Expr | null;
-        arity: number | null;
-        proper: boolean | null;
-        discard: boolean | null;
-        duplicate: boolean | null;
-        skip: Set<number> | null;
-        dup: Set<number> | null;
+        expr?: Expr;
+        arity?: number;
+        proper?: boolean;
+        discard?: boolean;
+        duplicate?: boolean;
+        skip?: Set<number>;
+        dup?: Set<number>;
     };
     _guess(options: any, preArgs?: any[], steps?: number): any;
     _aslist(): this[];
@@ -96,23 +96,23 @@ export 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?}>}
      */
     lambdify(options?: {
-        max: number | null;
-        maxArgs: number | null;
-        varGen: (arg0: void) => FreeVar | null;
-        steps: number | null;
-        html: boolean | null;
-        latin: number | null;
+        max?: number;
+        maxArgs?: number;
+        varGen?: (arg0: void) => FreeVar;
+        steps?: number;
+        html?: boolean;
+        latin?: number;
     }): IterableIterator<{
         expr: Expr;
         steps: number | null;
@@ -130,14 +130,6 @@ export class Expr {
         expr: Expr;
         steps: number;
     }>;
-    /**
-     * @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: IterableIterator<string>): Expr;
     _rski(options: any): this;
     /**
        * Apply self to list of given args.
@@ -147,13 +139,17 @@ export class Expr {
        */
     reduce(args: Expr[]): Expr | 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: FreeVar, value: Expr): Expr | 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: Expr, replace: Expr): Expr | null;
     /**
        * @desc iterate one step of calculation in accordance with known rules.
        * @return {{expr: Expr, steps: number, changed: boolean}}
@@ -207,24 +203,64 @@ export class Expr {
      */
     expect(expected: Expr, comment?: string): void;
     /**
-     * @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?: {
-        terse: boolean | null;
-        html: boolean | null;
-    }): string;
+    toString(): string;
     /**
      * @desc Whether the expression needs parentheses when printed.
      * @param {boolean} [first] - whether this is the first term in a sequence
      * @return {boolean}
      */
-    needsParens(first?: boolean): boolean;
+    _braced(first?: boolean): boolean;
+    _unspaced(arg: any): boolean;
     /**
+     * @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(): string;
+    format(options?: {
+        terse?: boolean;
+        html?: boolean;
+        brackets?: [string, string];
+        var?: [string, string];
+        lambda?: [string, string, string];
+        around?: [string, string];
+        redex?: [string, string];
+        inventory?: {
+            [x: string]: Expr;
+        };
+    }): string;
+    _format(options: any, nargs: any): void;
+    _declare(output: any, inventory: any, seen: any): void;
 }
 export namespace Expr {
     let lambdaPlaceholder: Native;
@@ -245,8 +281,7 @@ export class App extends Expr {
     _firstVar(): any;
     apply(...args: any[]): App;
     expand(): any;
-    renameVars(seq: any): any;
-    subst(plug: any, value: any): any;
+    subst(search: any, replace: any): any;
     /**
      * @return {{expr: Expr, steps: number}}
      */
@@ -259,14 +294,13 @@ export class App extends Expr {
     _aslist(): any[];
     equals(other: any): any;
     contains(other: any): any;
-    needsParens(first: any): boolean;
-    toString(opt?: {}): string;
+    _braced(first: any): boolean;
+    _format(options: any, nargs: any): any;
+    _unspaced(arg: any): any;
 }
 export class FreeVar extends Named {
     constructor(name: any);
     id: number;
-    subst(plug: any, value: any): any;
-    toString(opt?: {}): string;
 }
 export class Lambda extends Expr {
     /**
@@ -278,13 +312,12 @@ export class Lambda extends Expr {
     impl: Expr;
     arity: number;
     reduce(input: any): Expr;
-    subst(plug: any, value: any): Lambda;
+    subst(search: any, replace: any): Lambda;
     expand(): Lambda;
-    renameVars(seq: any): Lambda;
     _rski(options: any): any;
     equals(other: any): boolean;
-    toString(opt?: {}): string;
-    needsParens(first: any): boolean;
+    _format(options: any, nargs: any): string;
+    _braced(first: any): boolean;
 }
 /**
  * @typedef {function(Expr): Expr | AnyArity} AnyArity
@@ -334,7 +367,7 @@ export class Alias extends Named {
     proper: any;
     terminal: any;
     canonical: any;
-    subst(plug: any, value: any): Expr;
+    subst(search: any, replace: any): any;
     /**
      *
      * @return {{expr: Expr, steps: number}}
@@ -346,8 +379,8 @@ export class Alias extends Named {
     reduce(args: any): Expr;
     equals(other: any): any;
     _rski(options: any): Expr;
-    toString(opt: any): string;
-    needsParens(first: any): boolean;
+    _braced(first: any): boolean;
+    _format(options: any, nargs: any): string | void;
 }
 export class Church extends Native {
     constructor(n: any);
@@ -361,6 +394,12 @@ export namespace globalOptions {
     let maxArgs: number;
 }
 export const native: {};
+/**
+ *
+ * @param {Expr[]} inventory
+ * @return {string[]}
+ */
+export function declare(inventory: Expr[]): string[];
 declare class Named extends Expr {
     /**
        * @desc a constant named 'name'
@@ -368,6 +407,6 @@ declare class Named extends Expr {
        */
     constructor(name: string);
     name: string;
-    toString(): string;
+    _format(options: any, nargs: any): string;
 }
 export {};

package/types/lib/parser.d.ts

@@ -2,21 +2,21 @@ export class SKI {
     /**
      *
      * @param {{
-     *    allow: string?,
-     *    numbers: boolean?,
-     *    lambdas: boolean?,
-     *    terms: { [key: string]: Expr|string}?,
-     *    annotate: boolean?,
+     *    allow?: string,
+     *    numbers?: boolean,
+     *    lambdas?: boolean,
+     *    terms?: { [key: string]: Expr|string} | string[],
+     *    annotate?: boolean,
      * }} [options]
      */
     constructor(options?: {
-        allow: string | null;
-        numbers: boolean | null;
-        lambdas: boolean | null;
-        terms: {
+        allow?: string;
+        numbers?: boolean;
+        lambdas?: boolean;
+        terms?: {
             [key: string]: Expr | string;
-        } | null;
-        annotate: boolean | null;
+        } | string[];
+        annotate?: boolean;
     });
     annotate: boolean;
     known: {};
@@ -35,6 +35,14 @@ export class SKI {
         fast: boolean | null;
     }], note?: string): SKI;
     maybeAdd(name: any, impl: any): this;
+    /**
+     * @desc Declare and remove multiple terms at once
+     *       term=impl adds term
+     *       term= removes term
+     * @param {string[]]} list
+     * @return {SKI} chainable
+     */
+    bulkAdd(list: any): SKI;
     /**
      * Restrict the interpreter to given terms. Terms prepended with '+' will be added
      * and terms preceeded with '-' will be removed.
@@ -65,6 +73,11 @@ export class SKI {
     getTerms(): {
         [key: string]: Native | Alias;
     };
+    /**
+     * Export term declarations for use in bulkAdd().
+     * @returns {string[]}
+     */
+    declare(): string[];
     /**
      *
      * @param {string} source
@@ -94,13 +107,12 @@ export class SKI {
         allow: string | null;
     }): Expr;
     toJSON(): {
+        version: string;
         allow: string;
         numbers: boolean;
         lambdas: boolean;
-        terms: {
-            [key: string]: Native | Alias;
-        };
         annotate: boolean;
+        terms: string[];
     };
 }
 export namespace SKI {