@dallaylaen/ski-interpreter 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.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

@@ -13895,7 +13895,6 @@ var Expr = class _Expr {
   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.
@@ -14492,7 +14491,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,
@@ -14512,8 +14511,8 @@ var Expr = class _Expr {
    * @returns {string}
    * @private
    */
-  _format(options, nargs) {
-    throw new Error("No _format() method defined in class " + this.constructor.name);
+  formatImpl(options, nargs) {
+    throw new Error("No formatImpl() method defined in class " + this.constructor.name);
   }
   /**
    * @desc Returns a string representation of the expression tree, with indentation to show structure.
@@ -14536,20 +14535,8 @@ 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.
@@ -14648,15 +14635,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 +14661,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 +14687,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 +14769,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 +14805,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 +14874,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 = {}) {
@@ -15242,9 +15243,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 +15371,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 +15914,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, {