@dallaylaen/ski-interpreter 2.5.0 → 2.5.2

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [2.5.2] - 2026-03-27
+
+### Changed
+
+- Make `Expr` class abstract (as was always intended)
+and mark its abstract/final/protected methods appropriately.
+
+## [2.5.1] - 2026-03-26
+
+### Changed
+
+- make diag() recursive (and simpler)
+- better types, get rid of some type casts (esp in traverse/fold)
+- some doc improvements
+- some test improvements
+- playground: add history removal
+
 ## [2.5.0] - 2026-03-15
 
 ### BREAKING CHANGES

package/README.md

@@ -7,9 +7,13 @@ This package contains a
 and [lambda calculus](https://en.wikipedia.org/wiki/Lambda_calculus)
 parser and interpreter focused on traceability and inspectability.
 
-It is written in plain JavaScript (with bolted on TypeScript support)
+It is written in TypeScript and JavaScript
 and can be used in Node.js or in the browser.
 
+A [playground](https://dallaylaen.github.io/ski-interpreter/)
+and a [quest page](https://dallaylaen.github.io/ski-interpreter/quest.html)
+containing interactive combinatory logic exercises of increasing difficulty are incuded.
+
 # Features:
 
 * SKI and BCKW combinators
@@ -40,7 +44,8 @@ and can be used in Node.js or in the browser.
 * <code>C x y z &mapsto; x z y</code> _// swapping_;
 * <code>W x y &mapsto; x y y</code> _//duplication_;
 
-The special combinator `+` will increment Church numerals, if they happen to come after it:
+The special combinator `+` will increment Church numerals,
+if they happen to come directly after it:
 
 * `+ 0` // 1
 * `2 + 3` // -> `+(+(3))` -> `+(4)` -> `5`
@@ -99,14 +104,14 @@ npm install @dallaylaen/ski-interpreter
   * `--verbose` - Show all evaluation steps
   * Example: `ski file script.ski`
 
-* **`infer <expression>`** - try to find equivalent lambda expression and display its properties if found. 
+* **`infer <expression>`** - try to find equivalent lambda expression and display its properties if found.
 
-* **`extract <expression> <known term> ...`** - 
+* **`extract <expression> <known term> ...`** -
   Replace parts of the expression that are equivalent to the known terms with the respective terms. Known terms must be normalizable.
 
-* **`search <expression> <known term> ...`** - 
-  Attempt to brute force an equivalent of the _expression_ using only the _known terms_.  
-  Only normalizable terms are currently supported. 
+* **`search <expression> <known term> ...`** -
+  Attempt to brute force an equivalent of the _expression_ using only the _known terms_.
+  Only normalizable terms are currently supported.
 
 * **`quest-lint <files...>`** - Validate quest definition files
   * `--solution <file>` - Load solutions from a JSON file for verification
@@ -297,6 +302,7 @@ for building interactive quest pages from JSON-encoded quest data;
 * [@ivanaxe](https://github.com/ivanaxe) for luring me into [icfpc 2011](http://icfpc2011.blogspot.com/2011/06/task-description-contest-starts-now.html) where I was introduced to combinators.
 * [@akuklev](https://github.com/akuklev) for explaining functional programming to me so many times that I actually got some idea.
 * [One happy fellow](https://github.com/happyfellow-one) whose [riddle](https://blog.happyfellow.dev/a-riddle/) trolled me into writing an early `traverse` prototype.
+* [Darkwing3125](https://github.com/Darkwing3125) for posting multiple bug reports and feature requests.
 
 # Prior art and inspiration
 

package/lib/ski-interpreter.cjs.js

@@ -13889,18 +13889,11 @@ var FormatOptionsSchema = external_exports.object({
   inventory: external_exports.record(external_exports.string(), external_exports.custom((v) => v instanceof Expr)).optional()
 });
 var Expr = class _Expr {
-  static {
-    this.control = control;
-  }
-  static {
-    this.native = native;
-  }
-  // rough estimate of the number of nodes in the tree
   /**
    *
    * @desc Define properties of the term based on user supplied options and/or inference results.
    *       Typically useful for declaring Native and Alias terms.
-   * @private
+   * @protected
    * @param {Object} options
    * @param {string} [options.note] - a brief description what the term does
    * @param {number} [options.arity] - number of arguments the term is waiting for (if known)
@@ -13975,6 +13968,7 @@ var Expr = class _Expr {
    * }} [options]
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {Expr|null}
+   * @final
    */
   traverse(options, change) {
     if (typeof options === "function") {
@@ -13988,7 +13982,8 @@ var Expr = class _Expr {
     return expr ?? null;
   }
   /**
-   * @private
+   * @protected
+   * @final
    * @param {Object} options
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {TraverseValue<Expr>}
@@ -14007,7 +14002,7 @@ var Expr = class _Expr {
     return action ? action(expr) : expr;
   }
   /**
-   * @private
+   * @protected
    * @param {Object} options
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {TraverseValue<Expr>}
@@ -14037,7 +14032,11 @@ var Expr = class _Expr {
    *
    * This method is experimental and may change in the future.
    *
+   * @example // count the number of nodes in the expression tree
+   * expr.fold(0, (acc, e) => acc + 1);
+   *
    * @experimental
+   * @final
    * @template T
    * @param {T} initial
    * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
@@ -14047,6 +14046,14 @@ var Expr = class _Expr {
     const [value] = unwrap(this._fold(initial, combine));
     return value ?? initial;
   }
+  /**
+   * @desc Internal method for fold(), which performs the actual folding.
+   *       Should be implemented in subclasses having any internal structure.
+   *
+   * @protected
+   * @param initial
+   * @param combine
+   */
   _fold(initial, combine) {
     return combine(initial, this);
   }
@@ -14090,6 +14097,7 @@ var Expr = class _Expr {
    *
    *       Use toLambda() if you want to get a lambda term in any case.
    *
+   * @final
    * @param {{max?: number, maxArgs?: number}} options
    * @return {TermInfo}
    */
@@ -14182,6 +14190,7 @@ var Expr = class _Expr {
    *
    *       See also Expr.walk() and Expr.toSKI().
    *
+   * @final
    * @param {{
    *   max?: number,
    *   maxArgs?: number,
@@ -14228,6 +14237,7 @@ var Expr = class _Expr {
    *
    *     See also Expr.walk() and Expr.toLambda().
    *
+   * @final
    * @param {{max?: number}} [options]
    * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
    */
@@ -14258,12 +14268,15 @@ var Expr = class _Expr {
     }
   }
   /**
-   * Replace all instances of plug in the expression with value and return the resulting expression,
+   * Replace all instances of `search` in the expression with `replace` 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.
+   * as they are impossible to compare without extensive computations.
+   *
    * Typically used on variables but can also be applied to other terms, e.g. aliases.
-   * See also Expr.traverse().
+   * See also Expr.traverse() for more flexible replacement of subterms.
+   *
    * @param {Expr} search
    * @param {Expr} replace
    * @return {Expr|null}
@@ -14304,6 +14317,7 @@ var Expr = class _Expr {
    * @desc Run uninterrupted sequence of step() applications
    *       until the expression is irreducible, or max number of steps is reached.
    *       Default number of steps = 1000.
+   * @final
    * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
    * @param {Expr} args
    * @return {{expr: Expr, steps: number, final: boolean}}
@@ -14334,7 +14348,9 @@ var Expr = class _Expr {
   }
   /**
    * Execute step() while possible, yielding a brief description of events after each step.
+   *
    * Mnemonics: like run() but slower.
+   * @final
    * @param {{max?: number}} options
    * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
    */
@@ -14364,6 +14380,7 @@ var Expr = class _Expr {
    *
    * @param {Expr} other
    * @return {boolean}
+   * @final
    */
   equals(other) {
     return !this.diff(other);
@@ -14382,6 +14399,8 @@ var Expr = class _Expr {
    *       To somewhat alleviate confusion, the output will include
    *       the internal id of the variable in square brackets.
    *
+   *       Do not rely on the exact format of the output as it may change in the future.
+   *
    * @example  "K(S != I)" is the result of comparing "KS" and "KI"
    * @example  "S(K([x[13] != x[14]]))K"
    *
@@ -14402,6 +14421,11 @@ var Expr = class _Expr {
    * `this` is the expected value and the argument is the actual one.
    * Mnemonic: the expected value is always a combinator, the actual one may be anything.
    *
+   * In case of failure, an error is thrown with a message describing the first point of difference
+   * and `expected` and `actual` properties like in AssertionError.
+   * AssertionError is not used directly to because browsers don't recognize it.
+   *
+   * @final
    * @param {Expr} actual
    * @param {string} comment
    */
@@ -14421,7 +14445,10 @@ var Expr = class _Expr {
   /**
    * @desc Returns string representation of the expression.
    *       Same as format() without options.
+   *
+   *       Use formatImpl() to override in subclasses.
    * @return {string}
+   * @final
    */
   toString() {
     return this.format();
@@ -14430,6 +14457,7 @@ var Expr = class _Expr {
    * @desc Whether the expression needs parentheses when printed.
    * @param {boolean} [first] - whether this is the first term in a sequence
    * @return {boolean}
+   * @protected
    */
   _braced(_first) {
     return false;
@@ -14438,7 +14466,7 @@ var Expr = class _Expr {
    * @desc Whether the expression can be printed without a space when followed by arg.
    * @param {Expr} arg
    * @returns {boolean}
-   * @private
+   * @protected
    */
   _unspaced(arg) {
     return this._braced(true);
@@ -14446,8 +14474,9 @@ var Expr = class _Expr {
   /**
    * @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.
+   *          as well as `terse` and `html` flags that fill in appropriate defaults.
    *          Format without options is equivalent to toString() and can be parsed back.
+   * @final
    *
    * @param   {Object} [options]  - formatting options
    * @param   {boolean} [options.terse]   - whether to use terse formatting (omitting unnecessary spaces and parentheses)
@@ -14492,7 +14521,7 @@ var Expr = class _Expr {
       around: ["", ""],
       redex: ["", ""]
     };
-    return this._format({
+    return this.formatImpl({
       terse: options.terse ?? true,
       brackets: options.brackets ?? fallback.brackets,
       space: options.space ?? fallback.space,
@@ -14505,16 +14534,6 @@ var Expr = class _Expr {
       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);
-  }
   /**
    * @desc Returns a string representation of the expression tree, with indentation to show structure.
    *
@@ -14536,24 +14555,13 @@ var Expr = class _Expr {
    *       FreeVar: x[54]
    *       FreeVar: x[54]
    */
-  diag() {
-    const rec = (e, indent) => {
-      if (e instanceof App)
-        return [indent + "App:", ...e.unroll().flatMap((s) => rec(s, indent + "  "))];
-      if (e instanceof Lambda)
-        return [`${indent}Lambda (${e.arg}[${e.arg.id}]):`, ...rec(e.impl, indent + "  ")];
-      if (e instanceof Alias)
-        return [`${indent}Alias (${e.name}): \\`, ...rec(e.impl, indent)];
-      if (e instanceof FreeVar)
-        return [`${indent}FreeVar: ${e.name}[${e.id}]`];
-      return [`${indent}${e.constructor.name}: ${e}`];
-    };
-    const out = rec(this, "");
-    return out.join("\n");
+  diag(indent = "") {
+    return indent + this.constructor.name + ": " + this;
   }
   /**
    * @desc Convert the expression to a JSON-serializable format.
    * @returns {string}
+   * @final
    */
   toJSON() {
     return this.format();
@@ -14648,15 +14656,18 @@ var App = class _App extends Expr {
   _braced(first) {
     return !first;
   }
-  _format(options, nargs) {
-    const fun = this.fun._format(options, nargs + 1);
-    const arg = this.arg._format(options, 0);
+  formatImpl(options, nargs) {
+    const fun = this.fun.formatImpl(options, nargs + 1);
+    const arg = this.arg.formatImpl(options, 0);
     const wrap = nargs ? ["", ""] : options.around;
     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];
   }
+  diag(indent = "") {
+    return indent + "App:\n" + this.unroll().map((e) => e.diag(indent + "  ")).join("\n");
+  }
   _unspaced(arg) {
     return this.arg._braced(false) ? true : this.arg._unspaced(arg);
   }
@@ -14671,7 +14682,7 @@ var Named = class _Named extends Expr {
   _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) {
+  formatImpl(options, nargs) {
     const name = options.html ? this.fancyName ?? this.name : this.name;
     return this.arity !== void 0 && this.arity > 0 && this.arity <= nargs ? options.redex[0] + name + options.redex[1] : name;
   }
@@ -14697,10 +14708,13 @@ var FreeVar = class _FreeVar extends Named {
       return replace;
     return null;
   }
-  _format(options, nargs) {
+  formatImpl(options, nargs) {
     const name = options.html ? this.fancyName ?? this.name : this.name;
     return options.var[0] + name + options.var[1];
   }
+  diag(indent = "") {
+    return `${indent}FreeVar: ${this.name}[${this.id}]`;
+  }
   static {
     this.global = ["global"];
   }
@@ -14776,8 +14790,12 @@ var Lambda = class _Lambda extends Expr {
       return "(t->" + diff + ")";
     return null;
   }
-  _format(options, nargs) {
-    return (nargs > 0 ? options.brackets[0] : "") + options.lambda[0] + this.arg._format(options, 0) + options.lambda[1] + this.impl._format(options, 0) + options.lambda[2] + (nargs > 0 ? options.brackets[1] : "");
+  formatImpl(options, nargs) {
+    return (nargs > 0 ? options.brackets[0] : "") + options.lambda[0] + this.arg.formatImpl(options, 0) + options.lambda[1] + this.impl.formatImpl(options, 0) + options.lambda[2] + (nargs > 0 ? options.brackets[1] : "");
+  }
+  diag(indent = "") {
+    return `${indent}Lambda (${this.arg.name}[${this.arg.id}]):
+` + this.impl.diag(indent + "  ");
   }
   _braced(first) {
     return true;
@@ -14808,7 +14826,7 @@ var Church = class _Church extends Expr {
   _unspaced(arg) {
     return false;
   }
-  _format(options, nargs) {
+  formatImpl(options, nargs) {
     return nargs >= 2 ? options.redex[0] + this.n + options.redex[1] : this.n + "";
   }
 };
@@ -14877,9 +14895,13 @@ var Alias = class extends Named {
   _braced(first) {
     return this.outdated ? this.impl._braced(first) : false;
   }
-  _format(options, nargs) {
+  formatImpl(options, nargs) {
     const outdated = options.inventory ? options.inventory[this.name] !== this : this.outdated;
-    return outdated ? this.impl._format(options, nargs) : super._format(options, nargs);
+    return outdated ? this.impl.formatImpl(options, nargs) : super.formatImpl(options, nargs);
+  }
+  diag(indent = "") {
+    return `${indent}Alias (${this.name}): \\
+` + this.impl.diag(indent);
   }
 };
 function addNative(name, impl, opt = {}) {
@@ -14993,6 +15015,9 @@ var Empty = class extends Expr {
   postParse() {
     throw new Error("Attempt to use empty expression () as a term");
   }
+  formatImpl(options, nargs) {
+    return "()";
+  }
 };
 var PartialLambda = class _PartialLambda extends Empty {
   // TODO mutable! rewrite ro when have time
@@ -15242,9 +15267,7 @@ var Parser = class {
         list[j] = rework(list[j]);
         detour.set(needDetour[list[j].name], list[j]);
         env[list[j].name] = list[j];
-        console.log(`list[${j}] = ${list[j].name}=${list[j].impl};`);
       }
-      console.log("detour:", detour);
     }
     const out = list.map(
       (e) => needDetour[e.name] ? e.name + "=" + needDetour[e.name].name + "=" + e.impl.format({ inventory: env }) : e.name + "=" + e.impl.format({ inventory: env })
@@ -15372,22 +15395,6 @@ var Parser = class {
   /**
   *  Public static shortcuts to common functions (see also ./extras.js)
   */
-  /**
-  * @desc Create a proxy object that generates variables on demand,
-  *       with names corresponding to the property accessed.
-  *       Different invocations will return distinct variables,
-  *       even if with the same name.
-  *
-  *
-  * @example const {x, y, z} = SKI.vars();
-  *          x.name; // 'x'
-  *          x instanceof FreeVar; // true
-  *          x.apply(y).apply(z); // x(y)(z)
-  *
-  * @template T
-  * @param {T} [scope] - optional context to bind the generated variables to
-  * @return {{[key: string]: FreeVar}}
-  */
 };
 function maybeAlias(name, impl) {
   while (impl instanceof Alias && impl.name === name)
@@ -15931,7 +15938,17 @@ var SKI = class extends Parser {
   static {
     this.W = native.W;
   }
-  // variable generator shortcut
+  /**
+  * @desc Create a proxy object that generates variables on demand,
+  *       with names corresponding to the property accessed.
+  *       Different invocations will return distinct variables,
+  *       even if with the same name.
+  *
+  * @example const {x, y, z} = SKI.vars();
+  *          x.name; // 'x'
+  *          x instanceof FreeVar; // true
+  *          x.apply(y).apply(z); // x(y)(z)
+  */
   static vars(scope = {}) {
     const vars = {};
     return new Proxy(vars, {