@dallaylaen/ski-interpreter 2.5.1 → 2.5.2

package/CHANGELOG.md

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

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();
@@ -14994,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