@dallaylaen/ski-interpreter 2.5.0 → 2.5.2

package/lib/ski-interpreter.esm.js

@@ -13869,18 +13869,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)
@@ -13955,6 +13948,7 @@ var Expr = class _Expr {
    * }} [options]
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {Expr|null}
+   * @final
    */
   traverse(options, change) {
     if (typeof options === "function") {
@@ -13968,7 +13962,8 @@ var Expr = class _Expr {
     return expr ?? null;
   }
   /**
-   * @private
+   * @protected
+   * @final
    * @param {Object} options
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {TraverseValue<Expr>}
@@ -13987,7 +13982,7 @@ var Expr = class _Expr {
     return action ? action(expr) : expr;
   }
   /**
-   * @private
+   * @protected
    * @param {Object} options
    * @param {(e:Expr) => TraverseValue<Expr>} change
    * @returns {TraverseValue<Expr>}
@@ -14017,7 +14012,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
@@ -14027,6 +14026,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);
   }
@@ -14070,6 +14077,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}
    */
@@ -14162,6 +14170,7 @@ var Expr = class _Expr {
    *
    *       See also Expr.walk() and Expr.toSKI().
    *
+   * @final
    * @param {{
    *   max?: number,
    *   maxArgs?: number,
@@ -14208,6 +14217,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}>}
    */
@@ -14238,12 +14248,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}
@@ -14284,6 +14297,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}}
@@ -14314,7 +14328,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}>}
    */
@@ -14344,6 +14360,7 @@ var Expr = class _Expr {
    *
    * @param {Expr} other
    * @return {boolean}
+   * @final
    */
   equals(other) {
     return !this.diff(other);
@@ -14362,6 +14379,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"
    *
@@ -14382,6 +14401,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
    */
@@ -14401,7 +14425,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();
@@ -14410,6 +14437,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;
@@ -14418,7 +14446,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);
@@ -14426,8 +14454,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)
@@ -14472,7 +14501,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,
@@ -14485,16 +14514,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.
    *
@@ -14516,24 +14535,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();
@@ -14628,15 +14636,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);
   }
@@ -14651,7 +14662,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;
   }
@@ -14677,10 +14688,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"];
   }
@@ -14756,8 +14770,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;
@@ -14788,7 +14806,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 + "";
   }
 };
@@ -14857,9 +14875,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 = {}) {
@@ -14973,6 +14995,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
@@ -15222,9 +15247,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 })
@@ -15352,22 +15375,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)
@@ -15911,7 +15918,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, {