@dallaylaen/ski-interpreter 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.6.0] - 2026-03-28
+
+### BREAKING CHANGES
+
+- `Alias`: `outdated` and `terminal` properties replaced by
+`inline`: boolean.
+
+### Added
+
+- Experimental `Alias.makeInline()` that sets the inline property
+and adjusts the invocation accordingly
+- (don't wait for more args if inline).
+
+## [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
@@ -19,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### BREAKING CHANGES
 
-- `affine: true` in quests now means "has no duplicating subterms" rather than "non-duplicating as a whole." 
+- `affine: true` in quests now means "has no duplicating subterms" rather than "non-duplicating as a whole."
 Aliases are exempted from this check, so a solution `SK`
 will not pass as S is duplicating, but `false=SK; false`
 will because `false` (as a whole term) _is_ affine.
@@ -74,7 +94,7 @@ will because `false` (as a whole term) _is_ affine.
 ### Changed
 
 - `SKI.extras.foldr` is now removed in favor of
-`Expr.foldBottomUp<T>(fun: (expr: Expr, args: T[]) => T): T` 
+`Expr.foldBottomUp<T>(fun: (expr: Expr, args: T[]) => T): T`
 with the same semantics but more descriptive name
 and simpler signature.
 _Was experimental (and still is), so not considered a breaking change._

package/lib/ski-interpreter.cjs.js

@@ -13889,17 +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;
-  }
   /**
    *
    * @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)
@@ -13974,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") {
@@ -13987,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>}
@@ -14006,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>}
@@ -14036,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
@@ -14046,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);
   }
@@ -14089,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}
    */
@@ -14181,6 +14190,7 @@ var Expr = class _Expr {
    *
    *       See also Expr.walk() and Expr.toSKI().
    *
+   * @final
    * @param {{
    *   max?: number,
    *   maxArgs?: number,
@@ -14227,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}>}
    */
@@ -14257,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}
@@ -14303,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}}
@@ -14333,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}>}
    */
@@ -14363,6 +14380,7 @@ var Expr = class _Expr {
    *
    * @param {Expr} other
    * @return {boolean}
+   * @final
    */
   equals(other) {
     return !this.diff(other);
@@ -14381,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"
    *
@@ -14401,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
    */
@@ -14420,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();
@@ -14429,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;
@@ -14437,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);
@@ -14445,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)
@@ -14504,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
-   */
-  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.
    *
@@ -14541,6 +14561,7 @@ var Expr = class _Expr {
   /**
    * @desc Convert the expression to a JSON-serializable format.
    * @returns {string}
+   * @final
    */
   toJSON() {
     return this.format();
@@ -14809,8 +14830,8 @@ var Church = class _Church extends Expr {
     return nargs >= 2 ? options.redex[0] + this.n + options.redex[1] : this.n + "";
   }
 };
-function waitn(expr, n) {
-  return (arg) => n <= 1 ? expr.apply(arg) : waitn(expr.apply(arg), n - 1);
+function waitn(n) {
+  return n <= 1 ? (e) => (arg) => e.apply(arg) : (e) => (arg) => waitn(n - 1)(e.apply(arg));
 }
 var Alias = class extends Named {
   constructor(name, impl, options = {}) {
@@ -14819,17 +14840,28 @@ var Alias = class extends Named {
       throw new Error("Attempt to create an alias for a non-expression: " + impl);
     this.impl = impl;
     this._setup(options);
-    this.terminal = options.terminal ?? this.props?.proper;
-    this.invoke = waitn(impl, this.arity ?? 0);
+    this.invoke = waitn(options.inline ? 0 : this.arity ?? 0)(impl);
     this.size = impl.size;
-    if (options.outdated)
-      this.outdated = true;
+    if (options.inline)
+      this.inline = true;
+  }
+  /**
+   * @desc Make the alias inline, i.e. replace it with its implementation everywhere.
+   *
+   * Replaces the old `outdated` attribute.
+   * Used by the parser when a term definition is removed or updated.
+   *
+   * May change in future versions, use with caution.
+   *
+   * @experimental
+   * @returns {this}
+   */
+  makeInline() {
+    this.invoke = waitn(0)(this.impl);
+    this.inline = true;
+    return this;
   }
   /**
-   * @property {boolean} [outdated] - whether the alias is outdated
-   *     and should be replaced with its definition when encountered.
-   * @property {boolean} [terminal] - whether the alias should behave like a standalone term
-   *     // TODO better name?
    * @property {boolean} [proper] - whether the alias is a proper combinator (i.e. contains no free variables or constants)
    * @property {number} [arity] - the number of arguments the alias waits for before expanding
    * @property {Expr} [canonical] - equivalent lambda term.
@@ -14872,11 +14904,11 @@ var Alias = class extends Named {
     return other.diff(this.impl, !swap);
   }
   _braced(first) {
-    return this.outdated ? this.impl._braced(first) : false;
+    return this.inline ? this.impl._braced(first) : false;
   }
   formatImpl(options, nargs) {
-    const outdated = options.inventory ? options.inventory[this.name] !== this : this.outdated;
-    return outdated ? this.impl.formatImpl(options, nargs) : super.formatImpl(options, nargs);
+    const inline = options.inventory ? options.inventory[this.name] !== this : this.inline;
+    return inline ? this.impl.formatImpl(options, nargs) : super.formatImpl(options, nargs);
   }
   diag(indent = "") {
     return `${indent}Alias (${this.name}): \\
@@ -14994,6 +15026,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
@@ -15085,8 +15120,9 @@ var Parser = class {
     const named = this._named(term, impl);
     const opts = typeof options === "string" ? { note: options, canonize: false } : options ?? {};
     named._setup({ canonize: this.annotate, ...opts });
-    if (this.known[named.name])
-      this.known[named.name].outdated = true;
+    const old = this.known[named.name];
+    if (old instanceof Alias)
+      old.makeInline();
     this.known[named.name] = named;
     this.allow.add(named.name);
     return this;
@@ -15186,7 +15222,9 @@ var Parser = class {
    * @return {SKI}
    */
   remove(name) {
-    this.known[name].outdated = true;
+    const old = this.known[name];
+    if (old instanceof Alias)
+      old.makeInline();
     delete this.known[name];
     this.allow.delete(name);
     return this;
@@ -15271,7 +15309,7 @@ var Parser = class {
     let expr = new Empty();
     for (const item of lines) {
       if (expr instanceof Alias)
-        expr.outdated = true;
+        expr.makeInline();
       const def = item.match(/^([A-Z]|[a-z][a-z_0-9]*)\s*=(.*)$/s);
       if (def && def[2] === "")
         expr = new FreeVar(def[1], options.scope ?? FreeVar.global);
@@ -15285,7 +15323,7 @@ var Parser = class {
     }
     if (this.addContext) {
       if (expr instanceof Named)
-        expr = new Alias(expr.name, expr, { outdated: true });
+        expr = new Alias(expr.name, expr, { inline: true });
       expr.context = {
         env: { ...this.getTerms(), ...jar },
         // also contains pre-parsed terms
@@ -15393,7 +15431,7 @@ var Quest = class {
     for (const term of env ?? []) {
       const expr = this.engineFull.parse(term, { env: jar, scope: this });
       if (expr instanceof Alias)
-        this.env[expr.name] = new Alias(expr.name, expr.impl, { terminal: true, canonize: false });
+        this.env[expr.name] = new Alias(expr.name, expr.impl, { canonize: false });
       else if (expr instanceof FreeVar)
         this.env[expr.name] = expr;
       else
@@ -15482,7 +15520,7 @@ var Quest = class {
         if (e instanceof Named && arsenal[e.name] === e)
           return control.prune(a + 1);
       });
-      const expr = impl instanceof FreeVar ? impl : new Alias(spec.fancy ?? spec.name, impl, { terminal: true, canonize: false });
+      const expr = impl instanceof FreeVar ? impl : new Alias(spec.fancy ?? spec.name, impl, { canonize: false });
       jar[spec.name] = expr;
       prepared.push(expr);
     }