@dallaylaen/ski-interpreter 2.5.1 → 2.5.2

package/lib/types/expr.d.ts

@@ -54,7 +54,11 @@ export declare const FormatOptionsSchema: z.ZodObject<{
     inventory: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<Expr, Expr>>>;
 }, z.core.$strip>;
 export type FormatOptions = z.infer<typeof FormatOptionsSchema>;
-type RefinedFormatOptions = {
+/**
+ * @desc A version of FormatOptions with defaults plugged in,
+ *       use for mandatory formatImpl implementation in Expr subclasses.
+ */
+export type RefinedFormatOptions = {
     terse?: boolean;
     html?: boolean;
     brackets: [string, string];
@@ -69,14 +73,7 @@ type TraverseOptions = {
     order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost';
 };
 type TraverseCallback = (e: Expr) => TraverseValue<Expr>;
-export declare class Expr {
-    static control: {
-        descend: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        prune: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        redo: <T>(value?: T) => import("./internal").TraverseControl<T>;
-        stop: <T>(value?: T) => import("./internal").TraverseControl<T>;
-    };
-    static native: Record<string, Native>;
+export declare abstract class Expr {
     /**
      *  @desc A combinatory logic expression.
      *
@@ -110,7 +107,7 @@ export declare class Expr {
      *
      * @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)
@@ -165,17 +162,19 @@ export declare class Expr {
      * }} [options]
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {Expr|null}
+     * @final
      */
     traverse(options: TraverseOptions | TraverseCallback, change?: TraverseCallback): Expr | null;
     /**
-     * @private
+     * @protected
+     * @final
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {TraverseValue<Expr>}
      */
     _traverse_redo(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
     /**
-     * @private
+     * @protected
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {TraverseValue<Expr>}
@@ -201,13 +200,25 @@ export declare 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
      * @returns {T}
      */
     fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): T;
+    /**
+     * @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<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
     /**
      * @experimental
@@ -246,6 +257,7 @@ export declare class Expr {
      *
      *       Use toLambda() if you want to get a lambda term in any case.
      *
+     * @final
      * @param {{max?: number, maxArgs?: number}} options
      * @return {TermInfo}
      */
@@ -288,6 +300,7 @@ export declare class Expr {
      *
      *       See also Expr.walk() and Expr.toSKI().
      *
+     * @final
      * @param {{
      *   max?: number,
      *   maxArgs?: number,
@@ -312,6 +325,7 @@ export declare class Expr {
      *
      *     See also Expr.walk() and Expr.toLambda().
      *
+     * @final
      * @param {{max?: number}} [options]
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
@@ -321,12 +335,15 @@ export declare class Expr {
         final: boolean;
     }, void, unknown>;
     /**
-     * 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}
@@ -361,6 +378,7 @@ export declare 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}}
@@ -368,7 +386,9 @@ export declare class Expr {
     run(opt?: RunOptions | Expr, ...args: Expr[]): Run;
     /**
      * 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}>}
      */
@@ -386,6 +406,7 @@ export declare class Expr {
      *
      * @param {Expr} other
      * @return {boolean}
+     * @final
      */
     equals(other: Expr): boolean;
     /**
@@ -402,6 +423,8 @@ export declare 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"
      *
@@ -416,6 +439,11 @@ export declare 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
      */
@@ -423,27 +451,32 @@ export declare class Expr {
     /**
      * @desc Returns string representation of the expression.
      *       Same as format() without options.
+     *
+     *       Use formatImpl() to override in subclasses.
      * @return {string}
+     * @final
      */
     toString(): string;
     /**
      * @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?: boolean): boolean;
     /**
      * @desc Whether the expression can be printed without a space when followed by arg.
      * @param {Expr} arg
      * @returns {boolean}
-     * @private
+     * @protected
      */
     _unspaced(arg: Expr): boolean;
     /**
      * @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)
@@ -478,9 +511,10 @@ export declare class Expr {
      * @param {Object} options
      * @param {number} nargs
      * @returns {string}
-     * @private
+     * @protected
+     * @abstract
      */
-    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    abstract formatImpl(options: RefinedFormatOptions, nargs: number): string;
     /**
      * @desc Returns a string representation of the expression tree, with indentation to show structure.
      *
@@ -506,6 +540,7 @@ export declare class Expr {
     /**
      * @desc Convert the expression to a JSON-serializable format.
      * @returns {string}
+     * @final
      */
     toJSON(): string | object;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter. Supports SKI, BCKW, Church numerals, and setting up assertions ('quests') involving all of the above.",
   "keywords": [
     "combinatory logic",