@dallaylaen/ski-interpreter 1.3.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-02-12
+
+### BREAKING CHANGES
+
+- Quest: rename `vars` -> `env`, `title` -> `name`, and `descr` -> `intro`.
+- Quest: remove `subst` for good, use input: `{ name, fancy }` instead
+- App: remove `split()` method, use `foo.fun` and `foo.arg` directly or better yet `foo.unroll()` instead.
+
+### Added
+
+- `SKI.extras.search(seed: Expr[], options:{...}, predicate: (e: Expr, props: infer()) => 1|0|-1)` that brute forces all possible applications of `seed` (with some heuristics) returns the first matching expr (if can)
+- Add experimental `Expr.fold<T>(initial : T, combine: (acc : T, expr) => T?)` that folds an expression tree in LO order. Composite nodes are first checked as is and then descended into. If `combine` returns null, it is discarded and the previous value is kept.
+- Add `SKI.control.{descend, prune, stop}` helper functions for more precise `fold` control.
+- Add optional `Expr.context{ parser, scope, env, src }` which is filled by the parser.
+- Add `SKI.extras.deepFormat({}|[]|Expr|..., options={})` that recursively formats a deep structure with given options, leaving non-Expr values as is. Useful for debugging.
+- Add `Expr.toJSON()`, currently just `format()` with no options
+- Add `Expr.unroll()` that returns a list of terms
+that give the initial expression when applied
+from left to right: `((a, b), (c, d)) => [a, b, (c, d)]`
+
+## [2.0.0] - 2026-02-06
+
+### BREAKING CHANGES
+
+- Rename `guess()` to `infer()` for clarity;
+- Remove `replace()` method, use `subst()` or `traverse()` instead;
+- Rename `rewriteSKI` to `toSKI`, `lambdify` to `toLambda` for clarity and consistence;
+- Remove `getSymbols()` method. Partially replaced by traverse();
+- Remove `freeVars()` method (enumeration of vars is problematic with current scope impl);
+- Remove `contains()` method, use `any(e=>e.equals(other))` instead;
+- Remove `Expr.hasLambda()`, use `any(e => e instanceof Lambda)` instead;
+- Remove `postParse()` method (did nothing anyway and was only used in the parser);
+- Replace `parse(src, jar, options)` with `parse(src, options = { ..., env: jar })`;
+- Remove global `SKI.options`;
+- Remove `SKI.free()`, use `const {x, y} = SKI.vars()` instead.
+
+### Added
+
+- `expr.traverse(transform: Expr->Expr|null): Expr|null` for term traversal and replacement;
+- `expr.any(predicate: Expr->boolean)` method for matching expressions;
+- expr.diff(expr2) shows exactly where the terms begin differing (or returns null);
+- Parse now has 2 arguments: `ski.parse(src, options={})`:
+  - All `parse()` arguments are now immutable;
+  - Passing extra terms: `ski.parse(src, { env: { myterm } })`;
+  - Variable scope restriction: `ski.parse('x(y)', { scope: myObject })`;
+- `SKI.vars(scope?)` returns a magic proxy for variable declarations;
+- Added semi-official `Named.fancyName` property
+- `@typedef QuestResult` for better type definitions.
+
+### Changed
+
+- Parsing without context produces global free vars;
+- Better variable handling with scope/context distinction;
+- Quest system now uses `diff()` instead of `equals()` for more detailed comparisons.
+
 ## [1.3.0] - 2026-01-25
 
 ### BREAKING CHANGES

package/README.md

@@ -1,8 +1,8 @@
 # Simple Kombinator Interpreter
 
-This package contains a 
-[combinatory logic](https://en.wikipedia.org/wiki/Combinatory_logic) 
-and [lambda calculus](https://en.wikipedia.org/wiki/Lambda_calculus) 
+This package contains a
+[combinatory logic](https://en.wikipedia.org/wiki/Combinatory_logic)
+and [lambda calculus](https://en.wikipedia.org/wiki/Lambda_calculus)
 parser and interpreter focused on traceability and inspectability.
 
 It is written in plain JavaScript (with bolted on TypeScript support)
@@ -25,7 +25,7 @@ and can be used in Node.js or in the browser.
 * Whole non-negative numbers are interpreted as Church numerals, e.g. `5 x y` evaluates to `x(x(x(x(x y))))`. They must also be space-separated from other terms;
 * `x y z` is the same as `(x y) z` or `x(y)(z)` but **not** `x (y z)`;
 * Unknown terms are assumed to be free variables;
-* Lambda terms are written as `x->y->z->expr`, which is equivalent to 
+* Lambda terms are written as `x->y->z->expr`, which is equivalent to
 `x->(y->(z->expr))` (aka right associative). Free variables in a lambda expression ~~stay in Vegas~~ are isolated from terms with the same name outside it;
 * X = y z defines a new term.
 
@@ -38,6 +38,15 @@ and can be used in Node.js or in the browser.
 * <code>C x y z &mapsto; x z y</code> _// swapping_;
 * <code>W x y &mapsto; x y y</code> _//duplication_;
 
+The special combinator `+` will increment Church numerals, if they happen to come after it:
+
+* `+ 0` // 1
+* `2 + 3` // -> `+(+(3))` -> `+(4)` -> `5`
+
+The `term + 0` idiom may be used to convert
+numbers obtained via computation (e.g. factorials)
+back to human readable form.
+
 # Execution strategy
 
 Applications and native terms use normal strategy, i.e. the first term in the tree
@@ -48,15 +57,13 @@ all free variables are bound.
 
 # Playground
 
-https://dallaylaen.github.io/ski-interpreter/
+* [Interactive interpreter](https://dallaylaen.github.io/ski-interpreter/)
 
-* all of the above features (except comparison and JS-native terms) in your browser
-* expressions have permalinks
-* can configure verbosity & executeion speed
+  * all of the above features (except comparison and JS-native terms) in your browser
+  * expressions have permalinks
+  * can configure verbosity and execution speed
 
-# Quests
-
-https://dallaylaen.github.io/ski-interpreter/quest.html
+* [Quests](https://dallaylaen.github.io/ski-interpreter/quest.html)
 
 This page contains small tasks of increasing complexity.
 Each task requires the user to build a combinator with specific properties.
@@ -73,54 +80,134 @@ npm install @dallaylaen/ski-interpreter
 
 # Usage
 
+## A minimal example
+
+```javascript
+#!node
+
+const { SKI } = require('@dallaylaen/ski-interpreter');
+
+// Create a parser instance
+const ski = new SKI();
+
+// Parse an expression
+const expr = ski.parse(process.argv[2]);
+
+// Evaluate it step by step
+for (const step of expr.walk({max: 100})) {
+  console.log(`[${step.steps}] ${step.expr}`);
+}
+```
+
+## Main features
+
 ```javascript
-const {SKI} = require('@dallaylaen/ski-interpreter');
-const ski = new SKI(); // the parser
+const { SKI } = require('@dallaylaen/ski-interpreter');
+const ski = new SKI();
+
+const expr = ski.parse(src);
+
+// evaluating expressions
+const next = expr.step(); // { steps: 1, expr: '...' }
+const final = expr.run({max: 1000}); // { steps: 42, expr: '...' }
+const iterator = expr.walk();
+
+// applying expressions
+const result = expr.run({max: 1000}, arg1, arg2 ...);
+// same sa
+expr.apply(arg1).apply(arg2).run();
+// or simply
+expr.apply(arg1, arg2).run();
+
+// equality check
+ski.parse('x->y->x').equals(ski.parse('a->b->a')); // true
+ski.parse('S').equals(SKI.S); // true
+ski.parse('x').apply(ski.parse('y')).equals(ski.parse('x y')); // also true
+
+// defining new terms
+ski.add('T', 'CI'); // T x y = C I x y = I y x = y
+ski.add('M', 'x->x x'); // M x = x x
+
+// also with native JavaScript implementations:
+ski.add('V', x=>y=>f=>f.apply(x, y), 'pair constructor');
+
+ski.getTerms(); // all of the above as an object
+
+// converting lambda expressions to SKI
+const lambdaExpr = ski.parse('x->y->x y');
+const steps = [...lambdaExpr.toSKI()];
+// steps[steps.length - 1].expr only contains S, K, I, and free variables, if any
+
+// converting SKI expressions to lambda
+const skiExpr = ski.parse('S K K');
+const lambdaSteps = [...skiExpr.toLambda()];
+// lambdaSteps[lambdaSteps.length - 1].expr only contains lambda abstractions and applications
+```
+
+## Fancy formatting
 
-// parse an expression
-const expr = ski.parse('S(K(SI))K x y');
+The `format` methods of the `Expr` class supports
+a number of options, see [the source code](lib/expr.js) for details.
 
-// run the expression
-const result = expr.run({max: 100, throw: true});
-console.log('reached '+ result.expr + ' after ' + result.steps + ' steps.');
+## Variable scoping
 
-// inspect the steps taken to reach the result
-for (const step of expr.walk())
-  console.log(step.expr.toString());
+By default, parsed free variables are global and equal to any other variable with the same name.
+Variables inside lambdas are local to said lambda and will not be equal to anything except themselves.
 
-// convert lambda to SKI
-const lambda = ski.parse('x->y->z->x z y');
-for (const step of lambda.rewriteSKI())
-  console.log(step.steps + ': ' + step.expr);
+A special `scope` argument may be given to parse to limit the scope. It can be any object.
+
+```javascript
+const scope1 = {};
+const scope2 = {};
+const expr1 = ski.parse('x y', {scope: scope1});
+const expr2 = ski.parse('x y', {scope: scope2}); // not equal
+const expr3 = ski.parse('x y'); // equal to neither
+const expr4 = ski.parse('x', {scope: scope1}).apply(ski.parse('y', {scope: scope1})); // equal to expr1
+```
 
-// convert combinators to lambda
-const combinator = ski.parse('BSC');
-for (const step of combinator.lambdify())
-  console.log(step.steps + ': ' + step.expr);
+Variables can also be created using magic `SKI.vars(scope)` method:
 
-// compare expressions
-ski.parse('a->b->a').equals(ski.parse('x->y->x')); // true!
+```javascript
+const scope = {};
+const {x, y, z} = SKI.vars(scope); // no need to specify names
+```
 
-const jar = {}; // share free variables with the same names between parser runs
-ski.parse('a->b->f a').equals(ski.parse('x->y->f x')); // false
-ski.parse('a->b->f a', jar).equals(ski.parse('x->y->f x', jar)); // true 
+## Querying the expressions
 
-// define new terms
-ski.add('T', 'S(K(SI))K');
-console.log(ski.parse('T x y').run().expr); // prints 'x(y)'
+Expressions are trees, so they can be traversed.
 
-// define terms with JS implementation
-const jay = new SKI.classes.Native('J', a=>b=>c=>d=>a.apply(b).apply(a.apply(d).apply(c)));
-ski.add('J', jay);
+```javascript
+expr.any(e => e.equals(SKI.S)); // true if any subexpression is S
 
-// access predefined terms directly
-SKI.C.apply(SKI.S); // a term
-const [x, y] = SKI.free('x', 'y'); // free variables
-SKI.church(5).apply(x, y).run().expr + ''; // 'x(x(x(x(x y))))'
+expr.traverse(e => e.equals(SKI.I) ? SKI.S.apply(SKI.K, SKI.K) : null);
+// replaces all I's with S K K
+// here a returned `Expr` object replaces the subexpression,
+// whereas `null` means "leave it alone and descend if possible"
 ```
 
+## Test cases
 
+The `Quest` class may be used to build and execute test cases for combinators.
+
+```javascript
+const { Quest } = require('@dallaylaen/ski-interpreter');
+
+const q = new Quest({
+    name: 'Test combinator T',
+    description: 'T x y should equal y x',
+    input: 'T',
+    cases: [
+        ['T x y', 'y x'],
+    ],
+});
+
+q.check('CI'); // pass
+q.check('a->b->b a'); // ditto
+q.check('K'); // fail
+q.check('K(K(y x))') // nope! the variable scopes won't match
+```
 
+See [quest page data](docs/quest-data/) for more examples.
 
 # Thanks
 
@@ -138,4 +225,4 @@ SKI.church(5).apply(x, y).run().expr + ''; // 'x(x(x(x(x y))))'
 
 This software is free and available under the MIT license.
 
-&copy; Konstantin Uvarin 2024-2025
+&copy; Konstantin Uvarin 2024&ndash;2026

package/bin/ski.js

@@ -2,121 +2,120 @@
 
 const fs = require('node:fs/promises');
 
-const {SKI} = require('../index');
+const { SKI } = require('../index');
 
 const [myname, options, positional] = parseArgs(process.argv);
 
 if (options.help) {
-    console.error(myname + ': usage: ' + myname + '[-q | -v ] -e <expression>');
-    process.exit(1);
+  console.error(myname + ': usage: ' + myname + '[-q | -v ] -e <expression>');
+  process.exit(1);
 }
 
-if (typeof options.e === 'string' && positional.length > 0 || positional.length > 1) {
-    console.error(myname + ': either -e <expr> or exactly one filename must be given');
-    process.exit(1);
+if ((typeof options.e === 'string' && positional.length) > 0 || positional.length > 1) {
+  console.error(myname + ': either -e <expr> or exactly one filename must be given');
+  process.exit(1);
 }
 
 const ski = new SKI();
 
 if (options.e === undefined && !positional.length) {
-    // interactive console
-    const readline = require('readline');
-    const rl = readline.createInterface({
-        input:    process.stdin,
-        output:   process.stdout,
-        prompt:   '> ',
-        terminal: true,
-    });
-    if (!options.q)
-        console.log('Welcome to SKI interactive shell. Known combinators: '+ski.showRestrict());
-    rl.on('line', str => {
-        const flag = str.match(/^\s*([-+])([qvt])\s*$/);
-        if (flag) {
-            options[flag[2]] = flag[1] === '+';
-        } else {
-            runLine(err => {
-                console.log('' + err)
-            })(str);
-        }
-        rl.prompt();
-    });
-    rl.once('close', () => {
-        if (!options.q)
-            console.log('Bye, and may your bird fly high!');
-        process.exit(0)
-    });
+  // interactive console
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input:    process.stdin,
+    output:   process.stdout,
+    prompt:   '> ',
+    terminal: true,
+  });
+  if (!options.q)
+    console.log('Welcome to SKI interactive shell. Known combinators: ' + ski.showRestrict());
+  rl.on('line', str => {
+    const flag = str.match(/^\s*([-+])([qvt])\s*$/);
+    if (flag)
+      options[flag[2]] = flag[1] === '+';
+    else {
+      runLine(err => {
+        console.log('' + err)
+      })(str);
+    }
     rl.prompt();
+  });
+  rl.once('close', () => {
+    if (!options.q)
+      console.log('Bye, and may your bird fly high!');
+    process.exit(0)
+  });
+  rl.prompt();
 } else {
-    const prom = positional.length > 0
-        ? fs.readFile(positional[0], 'utf8')
-        : Promise.resolve(options.e);
-
-    prom.then(runLine(err => { console.error(''+err); process.exit(3)})).catch(err => {
-        console.error(myname + ': ' + err);
-        process.exit(2);
-    });
+  const prom = positional.length > 0
+    ? fs.readFile(positional[0], 'utf8')
+    : Promise.resolve(options.e);
+
+  prom.then(runLine(err => { console.error('' + err); process.exit(3) })).catch(err => {
+    console.error(myname + ': ' + err);
+    process.exit(2);
+  });
 }
 
-function runLine(onErr) {
-    return function(source) {
-        if (!source.match(/\S/))
-            return 0; // nothing to see here
-        try {
-            const expr = ski.parse(source);
-
-            const t0 = new Date();
-            for (let state of expr.walk()) {
-                if (state.final && !options.q)
-                    console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
-                if (options.v || state.final)
-                    console.log('' + state.expr.format({terse: options.t}));
-                if (state.final && expr instanceof SKI.classes.Alias)
-                    ski.add(expr.name, state.expr);
-            }
-            return 0;
-        } catch (err) {
-            onErr(err);
-            return 1;
-        }
+function runLine (onErr) {
+  return function (source) {
+    if (!source.match(/\S/))
+      return 0; // nothing to see here
+    try {
+      const expr = ski.parse(source);
+
+      const t0 = new Date();
+      for (const state of expr.walk()) {
+        if (state.final && !options.q)
+          console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
+        if (options.v || state.final)
+          console.log('' + state.expr.format({ terse: options.t }));
+        if (state.final && expr instanceof SKI.classes.Alias)
+          ski.add(expr.name, state.expr);
+      }
+      return 0;
+    } catch (err) {
+      onErr(err);
+      return 1;
     }
+  }
 }
 
-function parseArgs(argv) {
-    const [_, script, ...list] = argv;
-
-    const todo = {
-        '--':     () => { pos.push(...list) },
-        '--help': () => { opt.help = true },
-        '-q':     () => { opt.q = true },
-        '-v':     () => { opt.v = true },
-        '-c':     () => { opt.t = false },
-        '-t':     () => { opt.t = true },
-        '-e':     () => {
-            if (list.length < 1)
-                throw new Error('option ' + next + 'requires and argument');
-            opt.e = list.shift();
-        },
-    };
-
-    // TODO replace with a relevant dependency
-    const pos = [];
-    const opt = {};
-
-    while (list.length > 0) {
-        const next = list.shift();
-
-        if (!next.match(/^-/)) {
-            pos.push(next);
-            continue;
-        }
-
-        const action = todo[next];
-        if (typeof action !== "function")
-            throw new Error('Unknown option ' + next + '; see ski.js --help');
-
-        action();
+function parseArgs (argv) {
+  const [_, script, ...list] = argv;
+
+  const todo = {
+    '--':     () => { pos.push(...list) },
+    '--help': () => { opt.help = true },
+    '-q':     () => { opt.q = true },
+    '-v':     () => { opt.v = true },
+    '-c':     () => { opt.t = false },
+    '-t':     () => { opt.t = true },
+    '-e':     () => {
+      if (list.length < 1)
+        throw new Error('option -e requires an argument');
+      opt.e = list.shift();
+    },
+  };
+
+  // TODO replace with a relevant dependency
+  const pos = [];
+  const opt = {};
+
+  while (list.length > 0) {
+    const next = list.shift();
+
+    if (!next.match(/^-/)) {
+      pos.push(next);
+      continue;
     }
 
-    return [script, opt, pos];
-}
+    const action = todo[next];
+    if (typeof action !== 'function')
+      throw new Error('Unknown option ' + next + '; see ski.js --help');
+
+    action();
+  }
 
+  return [script, opt, pos];
+}

package/index.js

@@ -1,8 +1,16 @@
-const ski = require('./lib/parser');
+const main = require('./lib/parser');
 const quest = require('./lib/quest');
+const extras = require('./lib/extras');
 
-module.exports = { ...ski, ...quest };
-if (typeof window !== 'undefined') {
-  window.SKI = ski.SKI;
-  window.SKI.Quest = quest.Quest;
-}
+main.SKI.Quest = quest.Quest;
+main.SKI.extras = extras;
+
+// SKI_REPL=1 node -r ./index.js
+if (typeof process === 'object' && process.env.SKI_REPL && typeof global !== 'undefined')
+  global.SKI = main.SKI;
+
+// we're in a browser
+if (typeof window !== 'undefined')
+  window.SKI = main.SKI;
+
+module.exports = { ...main, ...quest };