@dallaylaen/ski-interpreter 1.0.1 → 1.1.0

package/lib/parser.js

@@ -191,6 +191,9 @@ class SKI {
    * @return {Expr}
    */
   parse (source, vars = {}, options = {}) {
+    if (typeof source !== 'string')
+      throw new Error('parse: source must be a string, got ' + typeof source);
+
     const lines = source.replace(/\/\/[^\n]*$/gm, '')
       .split(/\s*;[\s;]*/).filter( s => s.match(/\S/));
 

package/lib/quest.js

@@ -15,6 +15,26 @@ const { Expr, FreeVar, Alias, Lambda } = SKI.classes;
  * }} CaseResult
  */
 
+/**
+ * @typedef {{
+ *   linear: boolean?,
+ *   affine: boolean?,
+ *   normal: boolean?,
+ *   proper: boolean?,
+ *   discard: boolean?,
+ *   duplicate: boolean?,
+ *   arity: number?,
+ * }} Capability
+ */
+
+/**
+ * @typedef {
+ *   [string, string]
+ *   | [{max: number?}, string, string]
+ *   | [{caps: Capability, max: number?}, string]
+ * } TestCase
+ */
+
 class Quest {
   /**
    * @description A combinator problem with a set of test cases for the proposed solution.
@@ -27,7 +47,7 @@ class Quest {
    *    vars: string[]?,
    *    engine: SKI?,
    *    engineFull: SKI?,
-   *    cases: [{max: number?, note: string?, feedInput: boolean, lambdas: boolean?}|string[], ...string[][]]?
+   *    cases: TestCase[],
    * }} options
    */
   constructor (options = {}) {
@@ -124,8 +144,8 @@ class Quest {
 
     const input = this.input.map( t => t.placeholder );
     this.cases.push(
-      opt.linear
-        ? new LinearCase(input, opt, terms)
+      opt.caps
+        ? new PropertyCase(input, opt, terms)
         : new ExprCase(input, opt, terms)
     );
     return this;
@@ -275,30 +295,66 @@ class ExprCase extends Case {
   }
 }
 
-class LinearCase extends Case {
+const knownCaps = {
+  normal:    true,
+  proper:    true,
+  discard:   true,
+  duplicate: true,
+  linear:    true,
+  affine:    true,
+  arity:     true,
+}
+
+class PropertyCase extends Case {
   // test that an expression uses all of its inputs exactly once
   constructor (input, options, terms) {
     super(input, options);
+    if (terms.length > 1)
+      throw new Error('PropertyCase accepts exactly 1 string');
+    if (!options.caps || typeof options.caps !== 'object' || !Object.keys(options.caps).length)
+      throw new Error('PropertyCase requires a caps object with at least one capability');
+    const unknown = Object.keys(options.caps).filter( c => !knownCaps[c] );
+    if (unknown.length)
+      throw new Error('PropertyCase: don\'t know how to test these capabilities: ' + unknown.join(', '));
+
     this.expr = this.parse(terms[0]);
+    this.caps = options.caps;
+
+    if (this.caps.linear) {
+      delete this.caps.linear;
+      this.caps.duplicate = false;
+      this.caps.discard = false;
+      this.caps.normal = true;
+    }
+
+    if (this.caps.affine) {
+      delete this.caps.affine;
+      this.caps.normal = true;
+      this.caps.duplicate = false;
+    }
   }
 
   check (...expr) {
     const start = this.expr.apply(...expr);
     const r = start.run({ max: this.max });
-    const arity = r.expr.canonize();
-    const reason = arity.linear
-      ? null
-      : 'expected a linear expression, i.e. such that uses all inputs exactly once';
+    const guess = r.expr.guess({ max: this.max });
+
+    const reason = [];
+    for (const cap in this.caps) {
+      if (guess[cap] !== this.caps[cap])
+        reason.push('expected property ' + cap + ' to be ' + this.caps[cap] + ', found ' + guess[cap]);
+    }
+
     return {
-      pass:  !reason,
-      reason,
-      steps: r.steps,
+      pass:   !reason.length,
+      reason: reason ? reason.join('\n') : null,
+      steps:  r.steps,
       start,
-      found: r.expr,
-      case:  this,
-      note:  this.note,
-      args:  expr,
-    }
+      found:  r.expr,
+      case:   this,
+      note:   this.note,
+      args:   expr,
+    };
   }
 }
 

package/lib/util.js

@@ -54,13 +54,17 @@ function restrict (set, spec) {
   return out;
 }
 
-function missingIndices (arr, set) {
-  const out = new Set();
+function skipDup (arr, map) {
+  const skip = new Set();
+  const dup = new Set();
   for (let n = 0; n < arr.length; n++) {
-    if (!set.has(arr[n]))
-      out.add(n);
+    const count = map.get(arr[n]) ?? 0;
+    if (!count)
+      skip.add(n);
+    else if (count > 1)
+      dup.add(n);
   }
-  return out;
+  return [skip, dup];
 }
 
 function isSubset (a, b) {
@@ -71,4 +75,4 @@ function isSubset (a, b) {
   return true;
 }
 
-module.exports = { Tokenizer, restrict, missingIndices, isSubset };
+module.exports = { Tokenizer, restrict, skipDup, isSubset };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "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",
@@ -15,12 +15,17 @@
     "ski": "bin/ski.js"
   },
   "scripts": {
-    "test": "nyc mocha"
+    "lint": "npx eslint lib --ext .js,.ts",
+    "types": "npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly --outDir types",
+    "test": "npx nyc mocha",
+    "minify": "npx esbuild --bundle ./index.js --outfile=docs/build/js/ski-interpreter.min.js --minify --sourcemap",
+    "build": "npm run lint && npm run types && npm run test && npm run minify"
   },
   "files": [
     "package.json",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
     "lib",
     "types"
   ],
@@ -35,12 +40,14 @@
   },
   "homepage": "https://dallaylaen.github.io/ski-interpreter/index.html",
   "devDependencies": {
+    "chai": "^4.3.7",
+    "esbuild": "^0.25.10",
     "eslint": "^8.57.0",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-align-assignments": "^1.1.2",
     "eslint-plugin-import": "^2.29.1",
-    "typescript": "^5.8.2",
     "mocha": "^10.2.0",
-    "nyc": "^15.1.0"
+    "nyc": "^15.1.0",
+    "typescript": "^5.8.2"
   }
 }

package/types/lib/expr.d.ts

@@ -1,6 +1,5 @@
 export type AnyArity = (arg0: Expr) => Expr | AnyArity;
 export class Expr {
-    arity: number;
     /**
        * postprocess term after parsing. typically return self but may return other term or die
        * @return {Expr}
@@ -31,37 +30,67 @@ export class Expr {
      * @return {Map<Expr, number>}
      */
     getSymbols(): Map<Expr, number>;
+    /**
+     *   @desc Given a list of pairs of term, replaces every subtree
+     *         that is equivalent to the first term in pair with the second one.
+     *         If a simgle term is given, it is duplicated into a pair.
+     *
+     *   @example  S(SKK)(SKS).replace('I') = SII // we found 2 subtrees equivalent to I
+     *             and replaced them with I
+     *
+     *   @param {(Expr | [find: Expr, replace: Expr])[]} terms
+     *   @param {Object} [opt] - options
+     *   @return {Expr}
+     */
+    replace(terms: (Expr | [find: Expr, replace: Expr])[], opt?: any): Expr;
+    _replace(pairs: any, opt: any): any;
     /**
      * @desc rought estimate of the complexity of the term
      * @return {number}
      */
     weight(): number;
     /**
+     * @desc Try to find an equivalent lambda term for the expression,
+     *       returning also the term's arity and some other properties.
+     *
+     *       This is used internally when declaring a Native term,
+     *       unless {canonize: false} is used.
+     *
+     *       As of current it only recognizes terms that have a normal form,
+     *       perhaps after adding some variables. This may change in the future.
+     *
+     *       Use lambdify() if you want to get a lambda term in any case.
      *
-     * @param {{max: number?, maxArgs: number?, bestGuess?: Expr}} options
+     * @param {{max: number?, maxArgs: number?}} options
      * @return {{
-     *    found: boolean,
-     *    proper: boolean,
+     *    normal: boolean,
+     *    steps: number,
+     *    expr: Expr?,
      *    arity: number?,
-     *    linear: boolean?,
-     *    canonical?: Expr,
-     *    steps: number?,
-     *    skip: Set<number>?
+     *    proper: boolean?,
+     *    discard: boolean?,
+     *    duplicate: boolean?,
+     *    skip: Set<number>?,
+     *    dup: Set<number>?
      * }}
      */
-    canonize(options?: {
+    guess(options?: {
         max: number | null;
         maxArgs: number | null;
-        bestGuess?: Expr;
     }): {
-        found: boolean;
-        proper: boolean;
+        normal: boolean;
+        steps: number;
+        expr: Expr | null;
         arity: number | null;
-        linear: boolean | null;
-        canonical?: Expr;
-        steps: number | null;
+        proper: boolean | null;
+        discard: boolean | null;
+        duplicate: boolean | null;
         skip: Set<number> | null;
+        dup: Set<number> | null;
     };
+    _guess(options: any, preArgs?: any[], steps?: number): any;
+    _aslist(): this[];
+    _firstVar(): boolean;
     /**
      * @desc Returns a series of lambda terms equivalent to the given expression,
      *       up to the provided computation steps limit,
@@ -110,13 +139,6 @@ export class Expr {
      */
     renameVars(seq: IterableIterator<string>): Expr;
     _rski(options: any): this;
-    /**
-     * @desc Whether the term will reduce further if given more arguments.
-     *       In practice, equivalent to "starts with a FreeVar"
-     *       Used by canonize (duh...)
-     * @return {boolean}
-     */
-    wantsArgs(): boolean;
     /**
        * Apply self to list of given args.
        * Normally, only native combinators know how to do it.
@@ -172,13 +194,18 @@ export class Expr {
         steps: number;
     }>;
     /**
-       *
-       * @param {Expr} other
-       * @return {boolean}
-       */
+     *
+     * @param {Expr} other
+     * @return {boolean}
+     */
     equals(other: Expr): boolean;
     contains(other: any): boolean;
-    expect(other: any): void;
+    /**
+     * @desc Assert expression equality. Can be used in tests.
+     * @param {Expr} expected
+     * @param {string} comment
+     */
+    expect(expected: Expr, comment?: string): void;
     /**
      * @param {{terse: boolean?, html: boolean?}} [options]
      * @return {string} string representation of the expression
@@ -188,10 +215,11 @@ export class Expr {
         html: boolean | null;
     }): string;
     /**
-     *
+     * @desc Whether the expression needs parentheses when printed.
+     * @param {boolean} [first] - whether this is the first term in a sequence
      * @return {boolean}
      */
-    needsParens(): boolean;
+    needsParens(first?: boolean): boolean;
     /**
      *
      * @return {string}
@@ -209,22 +237,16 @@ export class App extends Expr {
      * @param {Expr} args
      */
     constructor(fun: Expr, ...args: Expr);
-    fun: Expr;
-    args: Expr;
+    arg: any;
+    fun: any;
     final: boolean;
-    weight(): Expr;
-    apply(...args: any[]): any;
-    canonize(options?: {}): {
-        found: boolean;
-        proper: boolean;
-        arity: number | null;
-        linear: boolean | null;
-        canonical?: Expr;
-        steps: number | null;
-        skip: Set<number> | null;
-    };
-    renameVars(seq: any): Expr;
-    subst(plug: any, value: any): Expr;
+    arity: any;
+    weight(): any;
+    _firstVar(): any;
+    apply(...args: any[]): App;
+    expand(): any;
+    renameVars(seq: any): any;
+    subst(plug: any, value: any): any;
     /**
      * @return {{expr: Expr, steps: number}}
      */
@@ -232,8 +254,12 @@ export class App extends Expr {
         expr: Expr;
         steps: number;
     };
+    reduce(args: any): any;
     split(): any[];
-    equals(other: any): boolean;
+    _aslist(): any[];
+    equals(other: any): any;
+    contains(other: any): any;
+    needsParens(first: any): boolean;
     toString(opt?: {}): string;
 }
 export class FreeVar extends Named {
@@ -250,6 +276,7 @@ export class Lambda extends Expr {
     constructor(arg: FreeVar | FreeVar[], impl: Expr);
     arg: FreeVar;
     impl: Expr;
+    arity: number;
     reduce(input: any): Expr;
     subst(plug: any, value: any): Lambda;
     expand(): Lambda;
@@ -257,6 +284,7 @@ export class Lambda extends Expr {
     _rski(options: any): any;
     equals(other: any): boolean;
     toString(opt?: {}): string;
+    needsParens(first: any): boolean;
 }
 /**
  * @typedef {function(Expr): Expr | AnyArity} AnyArity
@@ -283,7 +311,7 @@ export class Native extends Named {
     arity: any;
     note: any;
     apply(...args: any[]): Expr;
-    _rski(options: any): Expr | this;
+    _rski(options: any): any;
     reduce(args: any): any;
 }
 export class Alias extends Named {
@@ -319,6 +347,7 @@ export class Alias extends Named {
     equals(other: any): any;
     _rski(options: any): Expr;
     toString(opt: any): string;
+    needsParens(first: any): boolean;
 }
 export class Church extends Native {
     constructor(n: any);

package/types/lib/quest.d.ts

@@ -9,6 +9,15 @@ export type CaseResult = {
     args: typeof import("./expr").Expr[];
     case: Case;
 };
+export type Capability = {
+    linear: boolean | null;
+    affine: boolean | null;
+    normal: boolean | null;
+    proper: boolean | null;
+    discard: boolean | null;
+    duplicate: boolean | null;
+    arity: number | null;
+};
 /**
  * @typedef {{
  *   pass: boolean,
@@ -22,6 +31,24 @@ export type CaseResult = {
  *   case: Case
  * }} CaseResult
  */
+/**
+ * @typedef {{
+ *   linear: boolean?,
+ *   affine: boolean?,
+ *   normal: boolean?,
+ *   proper: boolean?,
+ *   discard: boolean?,
+ *   duplicate: boolean?,
+ *   arity: number?,
+ * }} Capability
+ */
+/**
+ * @typedef {
+ *   [string, string]
+ *   | [{max: number?}, string, string]
+ *   | [{caps: Capability, max: number?}, string]
+ * } TestCase
+ */
 export class Quest {
     /**
      * @description A combinator problem with a set of test cases for the proposed solution.
@@ -34,7 +61,7 @@ export class Quest {
      *    vars: string[]?,
      *    engine: SKI?,
      *    engineFull: SKI?,
-     *    cases: [{max: number?, note: string?, feedInput: boolean, lambdas: boolean?}|string[], ...string[][]]?
+     *    cases: TestCase[],
      * }} options
      */
     constructor(options?: {
@@ -46,12 +73,7 @@ export class Quest {
         vars: string[] | null;
         engine: SKI | null;
         engineFull: SKI | null;
-        cases: [{
-            max: number | null;
-            note: string | null;
-            feedInput: boolean;
-            lambdas: boolean | null;
-        } | string[], ...string[][]] | null;
+        cases: TestCase[];
     });
     engine: SKI;
     engineFull: SKI;

package/types/lib/util.d.ts

@@ -9,5 +9,5 @@ export class Tokenizer {
     split(str: string): string[];
 }
 export function restrict(set: any, spec: any): any;
-export function missingIndices(arr: any, set: any): any;
+export function skipDup(arr: any, map: any): any[];
 export function isSubset(a: any, b: any): boolean;