@dallaylaen/ski-interpreter 1.1.0 → 1.3.0

package/types/lib/expr.d.ts

@@ -1,4 +1,7 @@
-export type AnyArity = (arg0: Expr) => Expr | AnyArity;
+export type Partial = Expr | ((arg0: Expr) => Partial);
+/**
+ * @typedef {Expr | function(Expr): Partial} Partial
+ */
 export class Expr {
     /**
        * postprocess term after parsing. typically return self but may return other term or die
@@ -65,13 +68,13 @@ export class Expr {
      * @return {{
      *    normal: boolean,
      *    steps: number,
-     *    expr: Expr?,
-     *    arity: number?,
-     *    proper: boolean?,
-     *    discard: boolean?,
-     *    duplicate: boolean?,
-     *    skip: Set<number>?,
-     *    dup: Set<number>?
+     *    expr?: Expr,
+     *    arity?: number,
+     *    proper?: boolean,
+     *    discard?: boolean,
+     *    duplicate?: boolean,
+     *    skip?: Set<number>,
+     *    dup?: Set<number>,
      * }}
      */
     guess(options?: {
@@ -80,13 +83,13 @@ export class Expr {
     }): {
         normal: boolean;
         steps: number;
-        expr: Expr | null;
-        arity: number | null;
-        proper: boolean | null;
-        discard: boolean | null;
-        duplicate: boolean | null;
-        skip: Set<number> | null;
-        dup: Set<number> | null;
+        expr?: Expr;
+        arity?: number;
+        proper?: boolean;
+        discard?: boolean;
+        duplicate?: boolean;
+        skip?: Set<number>;
+        dup?: Set<number>;
     };
     _guess(options: any, preArgs?: any[], steps?: number): any;
     _aslist(): this[];
@@ -96,23 +99,23 @@ export class Expr {
      *       up to the provided computation steps limit,
      *       in decreasing weight order.
      * @param {{
-     *   max: number?,
-     *   maxArgs: number?,
-     *   varGen: function(void): FreeVar?,
-     *   steps: number?,
-     *   html: boolean?,
-     *   latin: number?,
+     *   max?: number,
+     *   maxArgs?: number,
+     *   varGen?: function(void): FreeVar,
+     *   steps?: number,
+     *   html?: boolean,
+     *   latin?: number,
      * }} options
      * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
      * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
      */
     lambdify(options?: {
-        max: number | null;
-        maxArgs: number | null;
-        varGen: (arg0: void) => FreeVar | null;
-        steps: number | null;
-        html: boolean | null;
-        latin: number | null;
+        max?: number;
+        maxArgs?: number;
+        varGen?: (arg0: void) => FreeVar;
+        steps?: number;
+        html?: boolean;
+        latin?: number;
     }): IterableIterator<{
         expr: Expr;
         steps: number | null;
@@ -130,32 +133,41 @@ export class Expr {
         expr: Expr;
         steps: number;
     }>;
-    /**
-     * @desc Rename free variables in the expression using the given sequence
-     *       This is for eye-candy only, as the interpreter knows darn well hot to distinguish vars,
-     *       regardless of names.
-     * @param {IterableIterator<string>} seq
-     * @return {Expr}
-     */
-    renameVars(seq: IterableIterator<string>): Expr;
     _rski(options: any): this;
     /**
-       * Apply self to list of given args.
-       * Normally, only native combinators know how to do it.
-       * @param {Expr[]} args
-       * @return {Expr|null}
-       */
-    reduce(args: Expr[]): Expr | null;
+     * Replace all instances of plug in the expression with value 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.
+     * Typically used on variables but can also be applied to other terms, e.g. aliases.
+     * See also Expr.replace().
+     * @param {Expr} search
+     * @param {Expr} replace
+     * @return {Expr|null}
+     */
+    subst(search: Expr, replace: Expr): Expr | null;
     /**
-       * Replace all instances of free vars with corresponding values and return the resulting expression.
-       * return null if no changes could be made.
-       * @param {FreeVar} plug
-       * @param {Expr} value
-       * @return {Expr|null}
-       */
-    subst(plug: FreeVar, value: Expr): Expr | null;
+     * @desc Apply term reduction rules, if any, to the given argument.
+     * A returned value of null means no reduction is possible.
+     * A returned value of Expr means the reduction is complete and the application
+     *     of this and arg can be replaced with the result.
+     * A returned value of a function means that further arguments are needed,
+     *     and can be cached for when they arrive.
+     *
+     * This method is between apply() which merely glues terms together,
+     *     and step() which reduces the whole expression.
+     *
+     * foo.invoke(bar) is what happens inside foo.apply(bar).step() before
+     *     reduction of either foo or bar is attempted.
+     *
+     * The name 'invoke' was chosen to avoid confusion with either 'apply' or 'reduce'.
+     *
+     * @param {Expr} arg
+     * @returns {Partial | null}
+     */
+    invoke(arg: Expr): Partial | null;
     /**
-       * @desc iterate one step of calculation in accordance with known rules.
+       * @desc iterate one step of a calculation.
        * @return {{expr: Expr, steps: number, changed: boolean}}
        */
     step(): {
@@ -207,24 +219,64 @@ export class Expr {
      */
     expect(expected: Expr, comment?: string): void;
     /**
-     * @param {{terse: boolean?, html: boolean?}} [options]
-     * @return {string} string representation of the expression
+     * @desc Returns string representation of the expression.
+     *       Same as format() without options.
+     * @return {string}
      */
-    toString(options?: {
-        terse: boolean | null;
-        html: boolean | null;
-    }): string;
+    toString(): string;
     /**
      * @desc Whether the expression needs parentheses when printed.
      * @param {boolean} [first] - whether this is the first term in a sequence
      * @return {boolean}
      */
-    needsParens(first?: boolean): boolean;
+    _braced(first?: boolean): boolean;
+    _unspaced(arg: any): 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.
+     *          Format without options is equivalent to toString() and can be parsed back.
+     *
+     * @param   {Object} [options]  - formatting options
+     * @param   {boolean} [options.terse]   - whether to use terse formatting (omitting unnecessary spaces and parentheses)
+     * @param   {boolean} [options.html]    - whether to default to HTML tags & entities
+     * @param   {[string, string]} [options.brackets]  - wrappers for application arguments, typically ['(', ')']
+     * @param   {[string, string]} [options.var]       - wrappers for variable names
+     *                                (will default to &lt;var&gt; and &lt;/var&gt; in html mode)
+     * @param   {[string, string, string]} [options.lambda]    - wrappers for lambda abstractions, e.g. ['&lambda;', '.', '']
+     *                                where the middle string is placed between argument and body
+     *                                default is ['', '->', ''] or ['', '-&gt;', ''] for html
+     * @param   {[string, string]} [options.around]    - wrappers around (sub-)expressions.
+     *                                individual applications will not be wrapped, i.e. (a b c) but not ((a b) c)
+     * @param   {[string, string]} [options.redex]     - wrappers around the starting term(s) that have enough arguments to be reduced
+     * @param   {Object<string, Expr>} [options.inventory]     - if given, output aliases in the set as their names
+     *                                and any other aliases as the expansion of their definitions.
+     *                                The default is a cryptic and fragile mechanism dependent on a hidden mutable property.
+     * @returns {string}
+     *
+     * @example foo.format() // equivalent to foo.toString()
+     * @example foo.format({terse: false}) // spell out all parentheses
+     * @example foo.format({html: true}) // use HTML tags and entities
+     * @example foo.format({ around: ['(', ')'], brackets: ['', ''], lambda: ['(', '->', ')'] }) // lisp style, still back-parsable
+     * @exapmle foo.format({ lambda: ['&lambda;', '.', ''] }) // pretty-print for the math department
+     * @example foo.format({ lambda: ['', '=>', ''], terse: false }) // make it javascript
+     * @example foo.format({ inventory: { T } }) // use T as a named term, expand all others
      *
-     * @return {string}
      */
-    toJSON(): string;
+    format(options?: {
+        terse?: boolean;
+        html?: boolean;
+        brackets?: [string, string];
+        var?: [string, string];
+        lambda?: [string, string, string];
+        around?: [string, string];
+        redex?: [string, string];
+        inventory?: {
+            [x: string]: Expr;
+        };
+    }): string;
+    _format(options: any, nargs: any): void;
+    _declare(output: any, inventory: any, seen: any): void;
 }
 export namespace Expr {
     let lambdaPlaceholder: Native;
@@ -243,10 +295,8 @@ export class App extends Expr {
     arity: any;
     weight(): any;
     _firstVar(): any;
-    apply(...args: any[]): App;
     expand(): any;
-    renameVars(seq: any): any;
-    subst(plug: any, value: any): any;
+    subst(search: any, replace: any): any;
     /**
      * @return {{expr: Expr, steps: number}}
      */
@@ -254,69 +304,88 @@ export class App extends Expr {
         expr: Expr;
         steps: number;
     };
-    reduce(args: any): any;
+    invoke(arg: any): any;
     split(): any[];
     _aslist(): any[];
     equals(other: any): any;
     contains(other: any): any;
-    needsParens(first: any): boolean;
-    toString(opt?: {}): string;
+    _braced(first: any): boolean;
+    _format(options: any, nargs: any): any;
+    _unspaced(arg: any): any;
 }
 export class FreeVar extends Named {
     constructor(name: any);
     id: number;
-    subst(plug: any, value: any): any;
-    toString(opt?: {}): string;
 }
 export class Lambda extends Expr {
     /**
-       * @param {FreeVar|FreeVar[]} arg
-       * @param {Expr} impl
-       */
-    constructor(arg: FreeVar | FreeVar[], impl: Expr);
+     * @desc Lambda abstraction of arg over impl.
+     *     Upon evaluation, all occurrences of 'arg' within 'impl' will be replaced
+     *     with the provided argument.
+     *
+     * Note that 'arg' will be replaced by a localized placeholder, so the original
+     * variable can be used elsewhere without interference.
+     * Listing symbols contained in the lambda will omit such placeholder.
+     *
+     * Legacy ([FreeVar], impl) constructor is supported but deprecated.
+     * It will create a nested lambda expression.
+     *
+     * @param {FreeVar} arg
+     * @param {Expr} impl
+     */
+    constructor(arg: FreeVar, impl: Expr);
     arg: FreeVar;
     impl: Expr;
     arity: number;
-    reduce(input: any): Expr;
-    subst(plug: any, value: any): Lambda;
+    invoke(arg: any): Expr;
+    subst(search: any, replace: any): Lambda;
     expand(): Lambda;
-    renameVars(seq: any): Lambda;
     _rski(options: any): any;
     equals(other: any): boolean;
-    toString(opt?: {}): string;
-    needsParens(first: any): boolean;
+    _format(options: any, nargs: any): string;
+    _braced(first: any): boolean;
 }
-/**
- * @typedef {function(Expr): Expr | AnyArity} AnyArity
- */
 export class Native extends Named {
     /**
-     * @desc A term named 'name' that converts next 'arity' arguments into
-     *       an expression returned by 'impl' function
-     *       If an apply: Expr=>Expr|null function is given, it will be attempted upon application
-     *       before building an App object. This allows to plug in argument coercions,
-     *       e.g. instantly perform a numeric operation natively if the next term is a number.
+     * @desc A named term with a known rewriting rule.
+     *       'impl' is a function with signature Expr => Expr => ... => Expr
+     *       (see typedef Partial).
+     *       This is how S, K, I, and company are implemented.
+     *
+     *       Note that as of current something like a=>b=>b(a) is not possible,
+     *       use full form instead: a=>b=>b.apply(a).
+     *
+     * @example new Native('K', x => y => x); // constant
+     * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
+     *
      * @param {String} name
-     * @param {AnyArity} impl
-     * @param {{note: string?, arity: number?, canonize: boolean?, apply: function(Expr):(Expr|null) }} [opt]
+     * @param {Partial} impl
+     * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
      */
-    constructor(name: string, impl: AnyArity, opt?: {
-        note: string | null;
-        arity: number | null;
-        canonize: boolean | null;
-        apply: (arg0: Expr) => (Expr | null);
+    constructor(name: string, impl: Partial, opt?: {
+        note?: string;
+        arity?: number;
+        canonize?: boolean;
+        apply?: (arg0: Expr) => (Expr | null);
     });
-    impl: AnyArity;
-    onApply: (arg0: Expr) => (Expr | null);
+    invoke: Partial;
     arity: any;
     note: any;
-    apply(...args: any[]): Expr;
     _rski(options: any): any;
-    reduce(args: any): any;
 }
 export class Alias extends Named {
     /**
-     * @desc An existing expression under a different name.
+     * @desc A named alias for an existing expression.
+     *
+     *     Upon evaluation, the alias expands into the original expression,
+     *     unless it has a known arity > 0 and is marked terminal,
+     *     in which case it waits for enough arguments before expanding.
+     *
+     *     A hidden mutable property 'outdated' is used to silently
+     *     replace the alias with its definition in all contexts.
+     *     This is used when declaring named terms in an interpreter,
+     *     to avoid confusion between old and new terms with the same name.
+     *
      * @param {String} name
      * @param {Expr} impl
      * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
@@ -334,7 +403,8 @@ export class Alias extends Named {
     proper: any;
     terminal: any;
     canonical: any;
-    subst(plug: any, value: any): Expr;
+    invoke: (arg: any) => any;
+    subst(search: any, replace: any): any;
     /**
      *
      * @return {{expr: Expr, steps: number}}
@@ -343,14 +413,18 @@ export class Alias extends Named {
         expr: Expr;
         steps: number;
     };
-    reduce(args: any): Expr;
     equals(other: any): any;
     _rski(options: any): Expr;
-    toString(opt: any): string;
-    needsParens(first: any): boolean;
+    _braced(first: any): boolean;
+    _format(options: any, nargs: any): string | void;
 }
 export class Church extends Native {
-    constructor(n: any);
+    /**
+     * @desc Church numeral representing non-negative integer n:
+     *      n f x = f(f(...(f x)...)) with f applied n times.
+     * @param {number} n
+     */
+    constructor(n: number);
     n: any;
     arity: number;
     equals(other: any): boolean;
@@ -361,6 +435,12 @@ export namespace globalOptions {
     let maxArgs: number;
 }
 export const native: {};
+/**
+ *
+ * @param {Expr[]} inventory
+ * @return {string[]}
+ */
+export function declare(inventory: Expr[]): string[];
 declare class Named extends Expr {
     /**
        * @desc a constant named 'name'
@@ -368,6 +448,6 @@ declare class Named extends Expr {
        */
     constructor(name: string);
     name: string;
-    toString(): string;
+    _format(options: any, nargs: any): string;
 }
 export {};

package/types/lib/parser.d.ts

@@ -2,21 +2,21 @@ export class SKI {
     /**
      *
      * @param {{
-     *    allow: string?,
-     *    numbers: boolean?,
-     *    lambdas: boolean?,
-     *    terms: { [key: string]: Expr|string}?,
-     *    annotate: boolean?,
+     *    allow?: string,
+     *    numbers?: boolean,
+     *    lambdas?: boolean,
+     *    terms?: { [key: string]: Expr|string} | string[],
+     *    annotate?: boolean,
      * }} [options]
      */
     constructor(options?: {
-        allow: string | null;
-        numbers: boolean | null;
-        lambdas: boolean | null;
-        terms: {
+        allow?: string;
+        numbers?: boolean;
+        lambdas?: boolean;
+        terms?: {
             [key: string]: Expr | string;
-        } | null;
-        annotate: boolean | null;
+        } | string[];
+        annotate?: boolean;
     });
     annotate: boolean;
     known: {};
@@ -24,17 +24,35 @@ export class SKI {
     hasLambdas: boolean;
     allow: any;
     /**
+     * @desc Declare a new term
+     * If the first argument is an Alias, it is added as is.
+     * Otherwise, a new Alias or Native term (depending on impl type) is created.
+     * If note is not provided and this.annotate is true, an automatic note is generated.
+     *
+     * If impl is a function, it should have signature (Expr) => ... => Expr
+     * (see typedef Partial at top of expr.js)
+     *
+     * @example ski.add('T', 'S(K(SI))K', 'swap combinator')
+     * @example ski.add( ski.parse('T = S(K(SI))K') ) // ditto but one-arg form
+     * @example ski.add('T', x => y => y.apply(x), 'swap combinator') // heavy artillery
+     * @example ski.add('Y', function (f) { return f.apply(this.apply(f)); }, 'Y combinator')
      *
      * @param {Alias|String} term
-     * @param {Expr|String|[number, function(...Expr): Expr, {note: string?, fast: boolean?}]} [impl]
+     * @param {String|Expr|function(Expr):Partial} [impl]
      * @param {String} [note]
      * @return {SKI} chainable
      */
-    add(term: Alias | string, impl?: Expr | string | [number, (...args: Expr[]) => Expr, {
-        note: string | null;
-        fast: boolean | null;
-    }], note?: string): SKI;
+    add(term: Alias | string, impl?: string | Expr | ((arg0: Expr) => Partial), note?: string): SKI;
+    _named(term: any, impl: any): Native | Alias;
     maybeAdd(name: any, impl: any): this;
+    /**
+     * @desc Declare and remove multiple terms at once
+     *       term=impl adds term
+     *       term= removes term
+     * @param {string[]]} list
+     * @return {SKI} chainable
+     */
+    bulkAdd(list: any): SKI;
     /**
      * Restrict the interpreter to given terms. Terms prepended with '+' will be added
      * and terms preceeded with '-' will be removed.
@@ -65,6 +83,11 @@ export class SKI {
     getTerms(): {
         [key: string]: Native | Alias;
     };
+    /**
+     * Export term declarations for use in bulkAdd().
+     * @returns {string[]}
+     */
+    declare(): string[];
     /**
      *
      * @param {string} source
@@ -94,13 +117,12 @@ export class SKI {
         allow: string | null;
     }): Expr;
     toJSON(): {
+        version: string;
         allow: string;
         numbers: boolean;
         lambdas: boolean;
-        terms: {
-            [key: string]: Native | Alias;
-        };
         annotate: boolean;
+        terms: string[];
     };
 }
 export namespace SKI {

package/types/lib/quest.d.ts

@@ -144,13 +144,31 @@ export class Quest {
     show(): TestCase[];
 }
 declare class Case {
-    constructor(input: any, options: any);
-    max: any;
-    note: any;
-    vars: any;
-    input: any;
-    engine: any;
-    parse(src: any): import("./expr").Lambda;
+    /**
+     * @param {FreeVar[]} input
+     * @param {{
+     *   max?: number,
+     *   note?: string,
+     *   vars?: {string: Expr},
+     *   engine: SKI
+     * }} options
+     */
+    constructor(input: typeof import("./expr").FreeVar[], options: {
+        max?: number;
+        note?: string;
+        vars?: {
+            string: typeof import("./expr").Expr;
+        };
+        engine: SKI;
+    });
+    max: number;
+    note: string;
+    vars: {
+        string?: typeof import("./expr").Expr;
+    };
+    input: typeof import("./expr").FreeVar[];
+    engine: SKI;
+    parse(src: any): Subst;
     /**
      * @param {Expr} expr
      * @return {CaseResult}
@@ -158,4 +176,15 @@ declare class Case {
     check(...expr: typeof import("./expr").Expr): CaseResult;
 }
 import { SKI } from "./parser";
+declare class Subst {
+    /**
+     * @descr A placeholder object with exactly n free variables to be substituted later.
+     * @param {Expr} expr
+     * @param {FreeVar[]} vars
+     */
+    constructor(expr: typeof import("./expr").Expr, vars: typeof import("./expr").FreeVar[]);
+    expr: typeof import("./expr").Expr;
+    vars: typeof import("./expr").FreeVar[];
+    apply(list: any): typeof import("./expr").Expr;
+}
 export {};