@dallaylaen/ski-interpreter 2.4.1 → 2.5.1

package/lib/types/expr.d.ts

@@ -1,18 +1,19 @@
-import { TraverseValue, Dict } from './internal';
+import { z } from 'zod';
+import { TraverseValue } from './internal';
 /**
  * @desc Control primitives for fold() and traverse() methods.
  */
 export declare const 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>;
+    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>;
 };
 /**
  * @desc List of predefined native combinators.
  * This is required for toSKI() to work, otherwise could as well have been in parser.js.
  */
-export declare const native: Dict<Native>;
+export declare const native: Record<string, Native>;
 export type TermInfo = {
     normal: boolean;
     proper: boolean;
@@ -41,17 +42,18 @@ export type RunOptions = {
     throw?: boolean;
     maxSize?: number;
 };
-export type FormatOptions = {
-    terse?: boolean;
-    html?: boolean;
-    brackets?: [string, string];
-    space?: string;
-    var?: [string, string];
-    lambda?: [string, string, string];
-    around?: [string, string];
-    redex?: [string, string];
-    inventory?: Dict<Expr>;
-};
+export declare const FormatOptionsSchema: z.ZodObject<{
+    terse: z.ZodOptional<z.ZodBoolean>;
+    html: z.ZodOptional<z.ZodBoolean>;
+    brackets: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    space: z.ZodOptional<z.ZodString>;
+    var: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    lambda: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
+    around: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    redex: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    inventory: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<Expr, Expr>>>;
+}, z.core.$strip>;
+export type FormatOptions = z.infer<typeof FormatOptionsSchema>;
 type RefinedFormatOptions = {
     terse?: boolean;
     html?: boolean;
@@ -61,7 +63,7 @@ type RefinedFormatOptions = {
     lambda: [string, string, string];
     around: [string, string];
     redex: [string, string];
-    inventory?: Dict<Expr>;
+    inventory?: Record<string, Expr>;
 };
 type TraverseOptions = {
     order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost';
@@ -69,40 +71,40 @@ type TraverseOptions = {
 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>;
+        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: Dict<Native>;
+    static native: Record<string, Native>;
     /**
-     *  @descr A combinatory logic expression.
+     *  @desc A combinatory logic expression.
      *
-     *  Applications, variables, and other terms like combinators per se
-     *  are subclasses of this class.
+     *  Applications, variables, lambdas, combinators per se,
+     *  and other expression subtypes all extend this class.
+     *
+     *  Expr itself cannot (or at least should not) be instantiated.
      *
      *  @abstract
-     *  @property {{
-     *    scope?: any,
-     *    env?: { [key: string]: Expr },
-     *    src?: string,
-     *    parser: object,
-     *  }} [context]
-     * @property {number} [arity] - number of arguments the term is waiting for (if known)
-     * @property {string} [note] - a brief description what the term does
-     * @property {string} [fancyName] - how to display in html mode, e.g. &phi; instead of 'f'
-     *                Typically only applicable to descendants of Named.
-     * @property {TermInfo} [props] - properties inferred from the term's behavior
      */
+    /** @desc optional context for the term. Is set by the parser with addContext: true */
     context?: {
         scope?: object;
-        env?: Dict<Expr>;
+        env?: Record<string, Expr>;
         src?: string;
         parser: object;
     };
+    /** @desc number of arguments the term is waiting for (if known) */
     arity?: number;
+    /** @desc a brief description what the term does */
     note?: string;
+    /** @desc the properties of the term, typically inferred from its behavior.
+     *      This is used internally when declaring Native / Alias terms.
+     */
     props?: TermInfo;
+    /** @desc An estimated number of nodes in the expression tree.
+     *     Used to prevent runaway computations.
+     */
     size?: number;
     /**
      *
@@ -262,7 +264,8 @@ export declare class Expr {
     _infer(options: {
         max: number;
         maxArgs: number;
-        skipNames: Dict<boolean>;
+        maxSize: number;
+        skipNames: Record<string, boolean>;
     }, nargs: number): TermInfo;
     /**
      * @desc Expand an expression into a list of terms
@@ -477,7 +480,7 @@ export declare class Expr {
      * @returns {string}
      * @private
      */
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
     /**
      * @desc Returns a string representation of the expression tree, with indentation to show structure.
      *
@@ -499,7 +502,7 @@ export declare class Expr {
      *       FreeVar: x[54]
      *       FreeVar: x[54]
      */
-    diag(): string;
+    diag(indent?: string): string;
     /**
      * @desc Convert the expression to a JSON-serializable format.
      * @returns {string}
@@ -530,7 +533,8 @@ export declare class App extends Expr {
     unroll(): Expr[];
     diff(other: Expr, swap?: boolean): string | null;
     _braced(first?: boolean): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     _unspaced(arg: Expr): boolean;
 }
 export declare class Named extends Expr {
@@ -543,7 +547,7 @@ export declare class Named extends Expr {
     fancyName?: string;
     constructor(name: string);
     _unspaced(arg: Expr): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
 export declare class FreeVar extends Named {
     /**
@@ -568,7 +572,8 @@ export declare class FreeVar extends Named {
     constructor(name: string, scope?: object);
     diff(other: Expr, swap?: boolean): string | null;
     subst(search: Expr, replace: Expr): Expr | null;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     static global: string[];
 }
 export declare class Native extends Named {
@@ -619,7 +624,8 @@ export declare class Lambda extends Expr {
     _fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
     subst(search: Expr, replace: Expr): Expr | null;
     diff(other: Expr, swap?: boolean): string | null;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
     _braced(first: boolean): boolean;
 }
 export declare class Church extends Expr {
@@ -632,7 +638,7 @@ export declare class Church extends Expr {
     constructor(n: number);
     diff(other: Expr, swap?: boolean): string | null;
     _unspaced(arg: Expr): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
 export declare class Alias extends Named {
     /**
@@ -660,6 +666,7 @@ export declare class Alias extends Named {
         maxArgs?: number;
         note?: string;
         terminal?: boolean;
+        outdated?: boolean;
     });
     /**
      * @property {boolean} [outdated] - whether the alias is outdated
@@ -680,7 +687,8 @@ export declare class Alias extends Named {
     step(): Step;
     diff(other: Expr, swap?: boolean): string | null;
     _braced(first: boolean): boolean;
-    _format(options: RefinedFormatOptions, nargs: number): string;
+    formatImpl(options: RefinedFormatOptions, nargs: number): string;
+    diag(indent?: string): string;
 }
 export declare const classes: {
     Expr: typeof Expr;

package/lib/types/index.d.ts

@@ -3,12 +3,12 @@ import { Parser } from './parser';
 import { Quest } from './quest';
 import { toposort } from './toposort';
 export declare class SKI extends Parser {
-    static native: import("./internal").Dict<import("./expr").Native>;
+    static native: Record<string, import("./expr").Native>;
     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>;
+        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 classes: {
         Expr: typeof import("./expr").Expr;
@@ -20,12 +20,36 @@ export declare class SKI extends Parser {
         Church: typeof Church;
         Alias: typeof import("./expr").Alias;
     };
+    static schemas: {
+        FormatOptions: import("zod").ZodObject<{
+            terse: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            html: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            brackets: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
+            space: import("zod").ZodOptional<import("zod").ZodString>;
+            var: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
+            lambda: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString, import("zod").ZodString], null>>;
+            around: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
+            redex: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
+            inventory: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodCustom<import("./expr").Expr, import("./expr").Expr>>>;
+        }, import("zod/v4/core").$strip>;
+    };
     static B: import("./expr").Native;
     static C: import("./expr").Native;
     static I: import("./expr").Native;
     static K: import("./expr").Native;
     static S: import("./expr").Native;
     static W: import("./expr").Native;
+    /**
+   * @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?: object): {
         [key: string]: FreeVar;
     };

package/lib/types/internal.d.ts

@@ -1,6 +1,3 @@
-export type Dict<T> = {
-    [key: string]: T;
-};
 export declare class Tokenizer {
     /**
      * @desc Create a tokenizer that splits strings into tokens according to the given terms.
@@ -27,8 +24,8 @@ export declare class Tokenizer {
  * @returns {Set<string>}
  */
 export declare function restrict(set: Set<string>, spec?: string): Set<string>;
-export type TraverseDecorator<T> = (value: T) => TraverseControl<T>;
-export type TraverseValue<T> = T | TraverseControl<T> | null | undefined;
+export type TraverseDecorator = <T>(value?: T) => TraverseControl<T>;
+export type TraverseValue<T> = TraverseControl<T | null | undefined | void> | T | null | undefined | void;
 export declare class TraverseControl<T> {
     /**
      * @desc A wrapper for values returned by fold/traverse callbacks
@@ -42,9 +39,9 @@ export declare class TraverseControl<T> {
      * @param {T} value
      * @param {function(T): TraverseControl<T>} decoration
      */
-    value: T;
-    decoration: TraverseDecorator<T>;
-    constructor(value: T, decoration: TraverseDecorator<T>);
+    value?: T;
+    decoration: TraverseDecorator;
+    constructor(value: T | undefined, decoration: TraverseDecorator);
 }
 /**
  * @private
@@ -52,7 +49,7 @@ export declare class TraverseControl<T> {
  * @param {T|TraverseControl<T>|null} value
  * @returns {[T?, function|undefined]}
  */
-export declare function unwrap<T>(value: TraverseValue<T>): [T?, TraverseDecorator<T>?];
+export declare function unwrap<T>(value: TraverseValue<T>): [T?, TraverseDecorator?];
 /**
  * @desc Prepare a self-referencing wrapper function for use as a fold/traverse control decorator.
  *
@@ -66,4 +63,4 @@ export declare function unwrap<T>(value: TraverseValue<T>): [T?, TraverseDecorat
  * @param {string} [label]
  * @returns {function(T): TraverseControl<T>}
  */
-export declare function prepareWrapper(label: string): <T>(value: T) => TraverseControl<T>;
+export declare function prepareWrapper(label?: string): <T>(value?: T) => TraverseControl<T>;

package/lib/types/parser.d.ts

@@ -7,6 +7,7 @@ export type ParserOptions = {
         [key: string]: Expr | string;
     } | string[];
     annotate?: boolean;
+    addContext?: boolean;
 };
 export type ParseOptions = {
     env?: {
@@ -34,6 +35,7 @@ export declare class Parser {
      *    annotate?: boolean,
      * }} [options]
      */
+    addContext: boolean;
     annotate: boolean;
     known: {
         [name: string]: Expr;

package/lib/types/quest.d.ts

@@ -220,7 +220,8 @@ declare class Case {
 }
 declare class Subst {
     /**
-     * @descr A placeholder object with exactly n free variables to be substituted later.
+     * @desc A placeholder object with exactly n free variables to be substituted later.
+     *        Basically a poor man's lambda.
      * @param {Expr} expr
      * @param {FreeVar[]} env
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "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",
@@ -64,6 +64,7 @@
     "typescript": "^5.8.2"
   },
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
   }
 }