@dallaylaen/ski-interpreter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Konstantin Uvarin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# 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) 
+parser and interpreter focused on traceability and inspectability.
+
+It is written in plain JavaScript (with bolted on TypeScript support)
+and can be used in Node.js or in the browser.
+
+# Features:
+
+* SKI and BCKW combinators
+* Lambda expressions
+* Church numerals
+* Defining new terms
+* λ ⇆ SKI conversion
+* Comparison of expressions
+* Includes a class for building and executing test cases for combinators
+
+# Syntax
+
+* Uppercase terms are always single characters and may be lumped together;
+* Lowercase alphanumeric terms may have multiple letters and must therefore be separated by spaces;
+* 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 
+`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.
+
+## Starting combinators:
+
+* `I x ↦ x` (identity);
+* `K x y ↦ x` (constant);
+* `S x y z ↦ x z (y z)` (fusion);
+* `B x y z ↦ x (y z)` (composition);
+* `C x y z ↦ y x z` (swapping);
+* `W x y z ↦ x (y z)` (duplication);
+
+# Execution strategy
+
+Applications and native terms use normal strategy, i.e. the first term in the tree
+that has enough arguments is executed and the step ends there.
+
+Lambda terms are lazy, i.e. the body is not touched until
+all free variables are bound.
+
+# Installation
+
+```bash
+npm install ski-interpreter
+```
+
+# Usage
+
+```javascript
+const {SKI} = require('@dallaylaen/ski-interpreter');
+const ski = new SKI(); // the parser
+
+// parse an expression
+const expr = ski.parse('S(K(SI))K x y');
+
+// run the expression
+const result = expr.run({max: 100, throw: true});
+console.log('reached '+ result.expr + ' after ' + result.steps + ' steps.');
+
+// inspect the steps taken to reach the result
+for (const step of expr.walk())
+  console.log(step.expr.toString());
+
+// 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);
+
+// convert combinators to lambda
+const combinator = ski.parse('BSC');
+for (const step of combinator.lambdify())
+  console.log(step.steps + ': ' + step.expr);
+
+// compare expressions
+ski.parse('a->b->a').equals(ski.parse('x->y->x')); // true!
+
+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 
+
+// define new terms
+ski.add('T', 'S(K(SI))K');
+console.log(ski.parse('T x y').run().expr); // prints 'x(y)'
+
+// 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);
+
+// 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))))'
+```
+
+# Playground
+
+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
+
+# 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.
+
+# CLI
+
+REPL comes with the package as [bin/ski.js](bin/ski.js).
+
+
+
+# Thanks
+
+* [@ivanaxe](https://github.com/ivanaxe) for luring me into [icfpc 2011](http://icfpc2011.blogspot.com/2011/06/task-description-contest-starts-now.html) where I was introduced to combinators.
+* [@akuklev](https://github.com/akuklev) for explaining functional programming to me so many times that I actually got some idea.
+
+# Prior art and inspiration
+
+* "To Mock The Mockingbird" by Raymond Smulian.
+* [combinator birds](https://www.angelfire.com/tx4/cus/combinator/birds.html) by [Chris Rathman](https://www.angelfire.com/tx4/cus/index.html)
+
+# License and copyright
+
+This software is free and available under the MIT license.
+
+© Konstantin Uvarin 2024-2025

package/bin/ski.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env -S node --stack-size=20600
+
+const fs = require('node:fs/promises');
+
+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);
+}
+
+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)
+    });
+    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);
+    });
+}
+
+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.toString({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();
+    }
+
+    return [script, opt, pos];
+}
+

package/index.js

@@ -0,0 +1,8 @@
+const ski = require('./lib/parser');
+const quest = require('./lib/quest');
+
+module.exports = { ...ski, ...quest };
+if (typeof window !== 'undefined') {
+  window.SKI = ski.SKI;
+  window.SKI.Quest = quest.Quest;
+}