@dallaylaen/ski-interpreter 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.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