@dallaylaen/ski-interpreter 2.7.0 → 2.8.1

package/lib/types/expr.d.ts

@@ -50,7 +50,7 @@ export type FormatOptions = {
     lambda?: [string, string, string];
     around?: [string, string];
     redex?: [string, string];
-    inventory?: Record<string, Expr>;
+    inventory?: Record<string, Named>;
 };
 /**
  *  A version of FormatOptions with defaults plugged in,
@@ -71,6 +71,10 @@ export type TraverseOptions = {
     order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost';
 };
 export type TraverseCallback = (e: Expr) => TraverseValue<Expr>;
+export type ToposortResult = {
+    list: Expr[];
+    env: Record<string, Named>;
+};
 /**
  *   A combinatory logic expression.
  *
@@ -102,10 +106,13 @@ export declare abstract class Expr {
      */
     size?: number;
     /**
+     * Add metadata based on user-supplied values and/or the properties of the term itself.
      *
-     *  Define properties of the term based on user supplied options and/or inference results.
-     *       Typically useful for declaring Native and Alias terms.
-     * @protected
+     * Typically applied to named terms shortly after instantiation.
+     *
+     * Experimental. Name and meaning may change in the future.
+     *
+     * @experimental
      * @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)
@@ -115,7 +122,7 @@ export declare abstract class Expr {
      * @param {number} [options.maxArgs] - maximum number of arguments for inference, if canonize is true
      * @return {this}
      */
-    _setup(options?: {
+    annotate(options?: {
         note?: string;
         arity?: number;
         fancy?: string;
@@ -553,12 +560,14 @@ export declare abstract class Expr {
      *       FreeVar: x[54]
      */
     diag(indent?: string): string;
+    declare(options?: FormatOptions & {
+        declaration?: [string, string, string];
+    }): string;
     /**
      * Convert the expression to a JSON-serializable format.
      * Sadly the format is not yet finalized and may change in the future.
      *
      * @experimental
-     * @returns {string}
      * @sealed
      */
     toJSON(): string | object;
@@ -763,6 +772,24 @@ export declare class Alias extends Named {
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
     diag(indent?: string): string;
 }
+/**
+ * Topologically sort a list of terms, extending it with any missing dependency terms,
+ * if necessary. The output list is guaranteed to contain at least the input terms.
+ *
+ * @param options
+ * @param [options.list] - a single expression or a list of expressions to sort.
+ * @param [options.env]  - a set of terms assumed to be known (and thus not required in the output list).
+ * @param [options.allow]  - a set of terms that are allowed in the returned list (aside from the input list).
+ *
+ * @example
+ *    const expr = ski.parse(src);
+ *    toposort([expr], ski.getTerms()); // returns all terms appearing in Expr in correct order
+ */
+export declare function toposort(options: {
+    list?: Expr | Expr[];
+    env?: Record<string, Named>;
+    allow?: Record<string, Named>;
+}): ToposortResult;
 export declare const classes: {
     Expr: typeof Expr;
     App: typeof App;

package/lib/types/extras.d.ts

@@ -1,5 +1,4 @@
-import { Expr, Named, FormatOptions, TermInfo } from './expr';
-import { toposort } from './toposort';
+import { Expr, Named, FormatOptions, TermInfo, toposort } from './expr';
 /**
  *   Extra utilities that do not belong in the core.
  */
@@ -52,48 +51,67 @@ export type SearchResult = {
     gen: number;
     cache?: Expr[][];
 };
-declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): SearchResult;
+export type EquivResult = {
+    steps: number;
+    equal: boolean;
+    normal: boolean;
+    canonical: [Expr | null, Expr | null];
+};
 /**
- *  Recursively replace all instances of Expr in a data structure with
- *       respective string representation using the format() options.
- *       Objects of other types and primitive values are eft as is.
+ *   Converts an unknown object into a FormatOptions, or returns an error it it is not valid.
+ *   A null/undefined counts as an empty options object (and is thus valid).
+ */
+declare function checkFormatOptions(raw: unknown): {
+    value: FormatOptions;
+} | {
+    error: Record<string, string>;
+};
+/**
+ * Find out if two expressions are computationally equivalent.
  *
- *       May be useful for debugging or diagnostic output.
+ * Unlike equals(), this function will attempt to normalize both expressions
+ * before comparing.
  *
  * @experimental
+ * @param e1
+ * @param e2
+ * @param options
  */
-declare function deepFormat(obj: any, options?: FormatOptions): any;
+declare function equiv(e1: Expr, e2: Expr, options?: {}): EquivResult;
 /**
  *   Given an expression and a hash of named terms,
- *        return a semicolon-separated string that declares said expression
- *        unambiguously.
+ *   return a semicolon-separated string that declares said expression
+ *   unambiguously.
  *
  * @example
  * var expr = ski.parse("T=CI; V=BCT; V x y");
  * SKI.extras.declare(expr, expr.context.env);
  * // 'B; C; I; T=CI; V=BC(T); x=; y=; Vx y'
  *
- * @param {Expr} expr
- * @param {{[s: string]: Named}} [env]
- * @returns {string}
  */
-declare function declare(expr: Expr, env?: {
-    [s: string]: Named;
-}): string;
+declare function declare(expr: Expr, env?: Record<string, Named>): string;
 /**
- *   Converts an unknown object into a FormatOptions, or returns an error it it is not valid.
- *   A null/undefined counts as an empty options object (and is thus valid).
+ *  Recursively replace all instances of Expr in a data structure with
+ *       respective string representation using the format() options.
+ *       Objects of other types and primitive values are eft as is.
+ *
+ *       May be useful for debugging or diagnostic output.
+ *
+ * @experimental
  */
-declare function checkFormatOptions(raw: unknown): {
-    value: FormatOptions;
-} | {
-    error: Record<string, string>;
-};
+declare function deepFormat(obj: any, options?: FormatOptions): any;
+/**
+ * @experimental
+ *   Look for an expression that matches the predicate,
+ *        starting with the seed and applying the terms to one another.
+ */
+declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): SearchResult;
 export declare const extras: {
     search: typeof search;
     deepFormat: typeof deepFormat;
     declare: typeof declare;
     toposort: typeof toposort;
     checkFormatOptions: typeof checkFormatOptions;
+    equiv: typeof equiv;
 };
 export {};

package/lib/types/index.d.ts

@@ -1,7 +1,6 @@
-import { FreeVar, Church } from './expr';
+import { FreeVar, Church, toposort } from './expr';
 import { Parser } from './parser';
 import { Quest } from './quest';
-import { toposort } from './toposort';
 export declare class SKI extends Parser {
     static native: Record<string, import("./expr").Native>;
     static control: {
@@ -44,15 +43,14 @@ export declare class SKI extends Parser {
     static extras: {
         search: (seed: import("./expr").Expr[], options: import("./extras").SearchOptions, predicate: import("./extras").SearchCallback) => import("./extras").SearchResult;
         deepFormat: (obj: any, options?: import("./expr").FormatOptions) => any;
-        declare: (expr: import("./expr").Expr, env?: {
-            [s: string]: import("./expr").Named;
-        }) => string;
+        declare: (expr: import("./expr").Expr, env?: Record<string, import("./expr").Named>) => string;
         toposort: typeof toposort;
         checkFormatOptions: (raw: unknown) => {
             value: import("./expr").FormatOptions;
         } | {
             error: Record<string, string>;
         };
+        equiv: (e1: import("./expr").Expr, e2: import("./expr").Expr, options?: {}) => import("./extras").EquivResult;
     };
     static Quest: typeof Quest;
 }

package/lib/types/parser.d.ts

@@ -1,4 +1,4 @@
-import { Expr, Alias, Native, Invocation } from './expr';
+import { Expr, Alias, Native, Named, Invocation } from './expr';
 export type ParserOptions = {
     allow?: string;
     numbers?: boolean;
@@ -17,6 +17,7 @@ export type ParseOptions = {
     numbers?: boolean;
     lambdas?: boolean;
     allow?: string;
+    canonize?: boolean;
 };
 export type AddOptions = {
     note?: string;
@@ -37,9 +38,7 @@ export declare class Parser {
      */
     addContext: boolean;
     annotate: boolean;
-    known: {
-        [name: string]: Expr;
-    };
+    known: Record<string, Named>;
     allow: Set<string>;
     hasNumbers: boolean;
     hasLambdas: boolean;
@@ -122,9 +121,7 @@ export declare class Parser {
      *
      * @return {{[key:string]: Native|Alias}}
      */
-    getTerms(): {
-        [key: string]: Expr;
-    };
+    getTerms(): Record<string, Named>;
     /**
      *  Export term declarations for use in bulkAdd().
      * Currently only Alias terms are serialized.
@@ -132,14 +129,15 @@ export declare class Parser {
      */
     declare(): string[];
     /**
-     * @template T
      * @param {string} source
      * @param {Object} [options]
-     * @param {{[keys: string]: Expr}} [options.env]
-     * @param {T} [options.scope]
-     * @param {boolean} [options.numbers]
-     * @param {boolean} [options.lambdas]
-     * @param {string} [options.allow]
+     * @param [options.env] - additional
+     * @param [options.scope] - assign this scope to unknown free variables
+     * @param {boolean} [options.numbers] - whether numbers are allowed
+     * @param {boolean} [options.lambdas] - whether lambdas are allowed
+     * @param {string} [options.allow] - restrict known terms
+     * @param [options.canonize] - whether to calculate canonical form, arity, and properties
+     *                             of intermediate aliases
      * @return {Expr}
      */
     parse(source: string, options?: ParseOptions): Expr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.7.0",
+  "version": "2.8.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",