@dallaylaen/ski-interpreter 2.2.0 → 2.3.0

package/types/src/parser.d.ts

@@ -24,7 +24,8 @@ export class SKI {
     };
     hasNumbers: boolean;
     hasLambdas: boolean;
-    allow: any;
+    /** @type {Set<string>} */
+    allow: Set<string>;
     /**
      * @desc Declare a new term
      * If the first argument is an Alias, it is added as is.
@@ -41,20 +42,41 @@ export class SKI {
      *
      * @param {Alias|String} term
      * @param {String|Expr|function(Expr):Partial} [impl]
-     * @param {String} [note]
+     * @param {object|string} [options]
+     * @param {string} [options.note] - optional annotation for the term, default is auto-generated if this.annotate is true
+     * @param {boolean} [options.canonize] - whether to canonize the term's implementation, default is this.annotate
+     * @param {boolean} [options.fancy] - alternative HTML-friendly name for the term
+     * @param {number} [options.arity] - custom arity for the term, default is inferred from the implementation
      * @return {SKI} chainable
      */
-    add(term: typeof classes.Alias | string, impl?: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial), note?: string): SKI;
-    _named(term: any, impl: any): classes.Alias | classes.Native;
-    maybeAdd(name: any, impl: any): this;
+    add(term: typeof classes.Alias | string, impl?: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial), options?: object | string): SKI;
+    /**
+     * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
+     * @param {Alias|string} term
+     * @param {string|Expr|function(Expr):Partial} impl
+     * @returns {Native|Alias}
+     * @private
+     */
+    private _named;
+    /**
+     * @desc Declare a new term if it is not known, otherwise just allow it.
+     *       Currently only used by quests.
+     *       Use with caution, this function may change its signature, behavior, or even be removed in the future.
+     *
+     * @experimental
+     * @param {string|Alias} name
+     * @param {string|Expr|function(Expr):Partial} impl
+     * @returns {SKI}
+     */
+    maybeAdd(name: string | typeof classes.Alias, impl: string | typeof classes.Expr | ((arg0: typeof classes.Expr) => Partial)): SKI;
     /**
      * @desc Declare and remove multiple terms at once
      *       term=impl adds term
      *       term= removes term
-     * @param {string[]]} list
+     * @param {string[]} list
      * @return {SKI} chainable
      */
-    bulkAdd(list: any): SKI;
+    bulkAdd(list: string[]): SKI;
     /**
      * Restrict the interpreter to given terms. Terms prepended with '+' will be added
      * and terms preceeded with '-' will be removed.
@@ -92,44 +114,46 @@ export class SKI {
      */
     declare(): string[];
     /**
-     *
+     * @template T
      * @param {string} source
      * @param {Object} [options]
      * @param {{[keys: string]: Expr}} [options.env]
-     * @param {any} [options.scope]
+     * @param {T} [options.scope]
      * @param {boolean} [options.numbers]
      * @param {boolean} [options.lambdas]
      * @param {string} [options.allow]
      * @return {Expr}
      */
-    parse(source: string, options?: {
+    parse<T_1>(source: string, options?: {
         env?: {
             [keys: string]: typeof classes.Expr;
         };
-        scope?: any;
+        scope?: T_1;
         numbers?: boolean;
         lambdas?: boolean;
         allow?: string;
     }): typeof classes.Expr;
     /**
-     *
+     * @desc Parse a single line of source code, without splitting it into declarations.
+     *       Internal, always use parse() instead.
+     * @template T
      * @param {String} source S(KI)I
      * @param {{[keys: string]: Expr}} env
      * @param {Object} [options]
      * @param {{[keys: string]: Expr}} [options.env] - unused, see 'env' argument
-     * @param {any} [options.scope]
+     * @param {T} [options.scope]
      * @param {boolean} [options.numbers]
      * @param {boolean} [options.lambdas]
      * @param {string} [options.allow]
      * @return {Expr} parsed expression
      */
-    parseLine(source: string, env?: {
+    parseLine<T_1>(source: string, env?: {
         [keys: string]: typeof classes.Expr;
     }, options?: {
         env?: {
             [keys: string]: typeof classes.Expr;
         };
-        scope?: any;
+        scope?: T_1;
         numbers?: boolean;
         lambdas?: boolean;
         allow?: string;
@@ -159,9 +183,11 @@ export namespace SKI {
      *          x instanceof FreeVar; // true
      *          x.apply(y).apply(z); // x(y)(z)
      *
+     * @template T
+     * @param {T} [scope] - optional context to bind the generated variables to
      * @return {{[key: string]: FreeVar}}
      */
-    export function vars(context?: {}): {
+    export function vars<T_1>(scope?: T_1): {
         [key: string]: typeof import("./expr").FreeVar;
     };
     /**
@@ -173,9 +199,10 @@ export namespace SKI {
     export { classes };
     export { native };
     export let control: {
-        descend: (arg0: any) => any;
-        prune: (arg0: any) => any;
-        stop: (arg0: any) => any;
+        descend: (arg0: T) => TraverseControl<T>;
+        prune: (arg0: T) => TraverseControl<T>;
+        redo: (arg0: T) => TraverseControl<T>;
+        stop: (arg0: T) => TraverseControl<T>;
     };
 }
 import classes = require("./expr");

package/types/src/quest.d.ts

@@ -1,22 +1,22 @@
 export type CaseResult = {
     pass: boolean;
-    reason: string | null;
+    reason?: string;
     steps: number;
     start: typeof import("./expr").Expr;
     found: typeof import("./expr").Expr;
     expected: typeof import("./expr").Expr;
-    note: string | null;
+    note?: string;
     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;
+    linear?: boolean;
+    affine?: boolean;
+    normal?: boolean;
+    proper?: boolean;
+    discard?: boolean;
+    duplicate?: boolean;
+    arity?: number;
 };
 export type InputSpec = string | {
     name: string;
@@ -34,35 +34,39 @@ export type QuestResult = {
     steps: number;
     weight?: number;
 };
+export type SelfCheck = {
+    accepted?: string[][];
+    rejected?: string[][];
+};
 /**
  * @typedef {{
  *   pass: boolean,
- *   reason: string?,
+ *   reason?: string,
  *   steps: number,
  *   start: Expr,
  *   found: Expr,
  *   expected: Expr,
- *   note: string?,
+ *   note?: string,
  *   args: Expr[],
  *   case: Case
  * }} CaseResult
  */
 /**
  * @typedef {{
- *   linear: boolean?,
- *   affine: boolean?,
- *   normal: boolean?,
- *   proper: boolean?,
- *   discard: boolean?,
- *   duplicate: boolean?,
- *   arity: number?,
+ *   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]
+ *   | [{max?: number}, string, string]
+ *   | [{caps: Capability, max?: number}, string]
  * } TestCase
  */
 /**
@@ -79,27 +83,32 @@ export type QuestResult = {
  *   weight?: number
  * }} QuestResult
  */
+/**
+ * @typedef {{
+ *    input: InputSpec | InputSpec[],
+ *    cases: TestCase[],
+ *
+ *    // the rest is optional
+ *
+ *    allow?: string,
+ *    numbers?: boolean,
+ *    env?: string[],
+ *    engine?: SKI,
+ *    engineFull?: SKI,
+ *
+ *    // metadata, also any fields not listed here will go to quest.meta.???
+ *    id?: string|number,
+ *    name?: string,
+ *    intro?: string|string[], // multiple strings will be concatenated with spaces
+ * }} QuestSpec
+ */
+/**
+ * @typedef {{ accepted?: string[][], rejected?: string[][] }} SelfCheck
+ */
 export class Quest {
     /**
      * @description A combinator problem with a set of test cases for the proposed solution.
-     * @param {{
-     *    input: InputSpec | InputSpec[],
-     *    cases: TestCase[],
-     *
-     *    // the rest is optional
-  
-     *    allow?: string,
-     *    numbers?: boolean,
-     *    env?: string[],
-     *    engine?: SKI,
-     *    engineFull?: SKI,
-     *
-     *    // metadata, also any fields not listed here will go to quest.meta.???
-     *    id?: string|number,
-     *    name?: string,
-     *    intro?: string|string[], // multiple strings will be concatenated with spaces
-     * }} options
-     *
+     * @param {QuestSpec} options
      * @example const quest = new Quest({
      *    input: 'identity',
      *    cases: [
@@ -114,11 +123,11 @@ export class Quest {
      *                       //     despite having the same name.
      * quest.check('I');     // fail! I not in the allowed list.
      */
-    constructor(options?: {});
+    constructor(options: QuestSpec);
     engine: any;
     engineFull: any;
     restrict: {
-        allow: any;
+        allow: QuestSpec;
         numbers: any;
         lambdas: any;
     };
@@ -129,7 +138,7 @@ export class Quest {
     name: any;
     intro: any;
     id: any;
-    meta: {};
+    meta: QuestSpec;
     /**
      *   Display allowed terms based on what engine thinks of this.env + this.restrict.allow
      *   @return {string}
@@ -158,12 +167,39 @@ export class Quest {
      * @return {QuestResult}
      */
     check(...input: string): QuestResult;
+    verify(options: any): {
+        date: string;
+    };
+    /**
+     * @desc Verify that solutions that are expected to pass/fail do so.
+     * @param {SelfCheck|{[key: string]: SelfCheck}} dataset
+     * @return {{shouldPass: {input: string[], result: QuestResult}[], shouldFail: {input: string[], result: QuestResult}[]} | null}
+     */
+    verifySolutions(dataset: SelfCheck | {
+        [key: string]: SelfCheck;
+    }): {
+        shouldPass: {
+            input: string[];
+            result: QuestResult;
+        }[];
+        shouldFail: {
+            input: string[];
+            result: QuestResult;
+        }[];
+    } | null;
+    verifyMeta(options?: {}): {
+        date: string;
+    };
     /**
        *
        * @return {TestCase[]}
        */
     show(): TestCase[];
 }
+export namespace Quest {
+    export { Group };
+    export { Case };
+}
 declare class Case {
     /**
      * @param {FreeVar[]} input
@@ -196,6 +232,16 @@ declare class Case {
      */
     check(...expr: typeof import("./expr").Expr): CaseResult;
 }
+declare class Group {
+    constructor(options: any);
+    name: any;
+    intro: string;
+    id: any;
+    content: any;
+    verify(options: any): {
+        content: any;
+    };
+}
 import { SKI } from "./parser";
 declare class Subst {
     /**