@thi.ng/lispy 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-05-20T19:06:30Z
+- **Last updated**: 2025-05-21T10:56:03Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/lispy@0.2.0) (2025-05-21)
+
+#### 🚀 Features
+
+- add more builtins & control flow ([a3b559c](https://github.com/thi-ng/umbrella/commit/a3b559c))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/lispy@0.1.0) (2025-05-20)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 208 standalone projects, maintained as part
+> This is one of 207 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,6 +15,22 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+- [Core language features](#core-language-features)
+  - [Constants](#constants)
+  - [Predicates](#predicates)
+  - [Basic math ops](#basic-math-ops)
+  - [Boolean logic operators](#boolean-logic-operators)
+  - [Bitwise operators](#bitwise-operators)
+  - [Comparison operators](#comparison-operators)
+  - [Constants & functions from JS-native `Math`](#constants--functions-from-js-native-math)
+  - [Selected utilities from thi.ng/math package](#selected-utilities-from-thingmath-package)
+  - [Functional programming](#functional-programming)
+  - [Control flow](#control-flow)
+  - [List/array/object processing](#listarrayobject-processing)
+  - [String processing](#string-processing)
+  - [Regexp](#regexp)
+  - [Misc utilities](#misc-utilities)
+- [Extensibility](#extensibility)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -27,76 +43,151 @@
 
 Lightweight, extensible, interpreted Lisp-style DSL for embedding in other projects.
 
-> [!NOTE] This DSL implementation has been extracted as standalone package from
+> [!NOTE]
+> This DSL implementation has been extracted as standalone package from
 > existing work/examples bundled in the thi.ng/umbrella monorepo (i.e.
 > [lispy-repl](https://github.com/thi-ng/umbrella/tree/develop/examples/lispy-repl))
 
-The core language is intentionally kept extremely minimal and currently only
-contains the following:
-
-- basic math ops (multi-arity)
-- logic operators (multi-arity)
-    - `and`
-    - `or`
-    - `not`
-- bitwise operators
-    - `<<`
-    - `>>` / `>>>`
-    - `bit-and`
-    - `bit-or`
-    - `bit-xor`
-    - `bit-not`
-- comparison operators
-- constants & functions from JS-native `Math`
-- selected utilities from [thi.ng/math](https://thi.ng/math) package
-    - `HALF_PI`
-    - `TAU`
-    - `clamp`: clamp value to interval
-    - `deg`: convert radians to degrees
-    - `fit`: fit value from one interval into another
-    - `mix`: linear interpolation (same as GLSL `mix()`)
-    - `rad`: convert degrees to radians
-    - `step`: same as GLSL `step()`
-    - `smoothstep`: same as GLSL `smoothstep()`
-- basic FP programming constructs
-    - `comp`: functional composition
-    - `def`: define global symbol
-    - `defn`: define global function
-    - `let`: locally scope var bindings/expression
-    - `partial`: partial application (currying)
-- basic list/array processing
-    - `aget`: get array index
-    - `aset`: set array index
-    - `count`: number of items
-    - `concat`: same as `Array.prototype.concat(...)`
-    - `filter`: list/array filtering
-    - `first`: first item of array
-    - `map`: list/array transformation
-    - `next`: remaining array items (after first)
-    - `push`: same as `Array.prototype.push(...)`
-    - `reduce`: list/array reduction
-- string/regexp processing
-    - `capitalize`
-    - `lower`
-    - `upper`
-    - `pad-left`
-    - `pad-right`
-    - `substr`
-    - `trim`
-    - `regexp`
-    - `re-match`
-    - `re-test`
-    - `replace`
-- misc utilities
-    - `print`: aka `console.log(...)`
-    - `env`: JSON stringified version of current root env
+## Core language features
+
+The core language is intentionally kept minimal, aimed at data transformations,
+and currently only contains the following:
+
+### Constants
+- `T`: true
+- `F`: false
+- `null`: null
+- `PI`
+- `HALF_PI`
+- `TAU`
+
+### Predicates
+
+- `(zero? x)`: zero check
+- `(nan? x)`: NaN check
+- `(neg? x)`: < 0 check
+- `(null? x)`: Null(ish) check
+- `(pos? x)`: > 0 check
+
+### Basic math ops
+
+- `(+ x y...)`
+- `(- x y...)`
+- `(* x y...)`
+- `(/ x y...)`
+- `(inc x)`: increment (+1)
+- `(dec x)`: decrement (-1)
+
+### Boolean logic operators
+
+- `(and x y ...)`
+- `(or x y ...)`
+- `(not x)`
+
+### Bitwise operators
+
+- `(<< x y)`
+- `(>> x y)`
+- `(>>> x y)`
+- `(bit-and x y)`
+- `(bit-or x y)`
+- `(bit-xor x y)`
+- `(bit-not x)`
+
+### Comparison operators
+
+- `(< x y)`
+- `(<= x y)`
+- `(> x y)`
+- `(>= x y)`
+- `(== x y)`
+- `(!= x y)`
+
+### Constants & functions from JS-native `Math`
+
+All included...
+
+### Selected utilities from thi.ng/math package
+
+- `(clamp x min max)`: clamp value to interval
+- `(deg x)`: convert radians to degrees
+- `(fit x a b c d)`: fit value from interval `[a..b]` into `[c..d]`
+- `(mix a b t)`: linear interpolation (same as GLSL `mix()`)
+- `(rad x)`: convert degrees to radians
+- `(smoothstep e1 e2 x)`: same as GLSL `smoothstep()`
+- `(step edge x)`: same as GLSL `step()`
+
+### Functional programming
+
+- `(always ...)`: function which always returns true
+- `(comp f g)`: functional composition
+- `(def name val)`: define global symbol
+- `(defn name (...args) body)`: define global function
+- `(fnull? x fn)`: function which returns `(fn)` if x is nullish
+- `(identity x)`: function which always returns its arg
+- `(never ...)`: function which always returns false
+- `(partial fn arg)`: partial application (currying)
+
+### Control flow
+
+- `(env! (sym val ...))`: modify bindings in current env
+- `(if test truthy falsey?)`: conditional with optional false branch
+- `(let (sym val ...) body)`: locally scoped var bindings/expression
+- `(while test body... (recur (...))?)`: loop while test is truthy
+- `(-> ...)`: Clojure-style thread-first S-expression re-writing
+    - `(-> a (+ b) (* c))` → `(* (+ a b) c)`
+- `(->> ...)`: Clojure-style thread-last S-expression re-writing
+    - `(->> a (+ b) (* c))` → `(* c (+ b a))`
+
+### List/array/object processing
+
+- `(get arr index)`: get array/object value at index/key
+- `(set! arr index value)`: set array/object value for index/key
+- `(concat x y ...)`: same as `Array.prototype.concat(...)`
+- `(count x)`: number of items (also for strings)
+- `(filter fn list)`: list/array filtering
+- `(first x)`: first item of array
+- `(map fn list)`: list/array transformation
+- `(next x)`: remaining array items (after first)
+- `(push arr x...)`: same as `Array.prototype.push(...)`
+- `(reduce fn init list)`: list/array reduction
+
+### String processing
+
+- `(capitalize x)`
+- `(float x)`: same as `parseFloat(x)`
+- `(int x radix?)`: same as `parseInt(x, radix)`
+- `(join sep arr)`: same as `Array.prototype.join(sep)`
+- `(lower x)`
+- `(pad-left x width fill)`
+- `(pad-right x width fill)`
+- `(str x...)`: coerce values to string, concat results
+- `(substr x from to?)`
+- `(trim x)`
+- `(upper x)`
+
+### Regexp
+
+- `(re-match re x)`
+- `(re-test re x)`
+- `(regexp str flags?)`
+- `(replace str regexp replacement)`
+
+### Misc utilities
+
+- `(env)`: JSON stringified version of current env
+- `(syms)`: Array of symbol names in current env
+- `(print x...)`: aka `console.log(...)`
+
+## Extensibility
 
 The core language can be easily customized/extended by defining new items in the
-root environment `ENV` (see example below).
+root environment `ENV` (see example below) or passing a custom environment to
+[`evalSource()`](https://docs.thi.ng/umbrella/lispyfunctions/evalSource.html).
 
 ## Status
 
-**ALPHA** - bleeding edge / work-in-progress
+**BETA** - possibly breaking changes forthcoming
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Blispy%5D+in%3Atitle)
 
@@ -126,7 +217,7 @@ For Node.js REPL:
 const lispy = await import("@thi.ng/lispy");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.50 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.92 KB
 
 ## Dependencies
 
@@ -179,28 +270,59 @@ const SRC = `
 (greetings! name)
 ;; hello, lispy!
 
+;; basic loop w/ local var
+(let (i 0)
+  (while (< i 5)
+    (print i)
+    (env! (i (inc i)))))
+;; 0
+;; 1
+;; 2
+;; 3
+;; 4
+
+;; threading/rewriting operators
+(->> name (str "hello, ") (print "result:"))
+;; result: hello, lispy
+
 ;; print contents of default environment
 (print (env))
 `;
 
+// execute with customized environment
 evalSource(SRC, {...ENV, name: "lispy"});
 
 // output:
 // 10
 // 65
-// hello, lispy!
-//
+// hello, lispy
+// 0
+// 1
+// 2
+// 3
+// 4
+// result: hello, lispy
 // {
 //   "+": "<function>",
 //   "*": "<function>",
 //   "-": "<function>",
 //   "/": "<function>",
+//   "inc": "<function>",
+//   "dec": "<function>",
+//   "null?": "<function>",
+//   "zero?": "<function>",
+//   "neg?": "<function>",
+//   "pos?": "<function>",
+//   "nan?": "<function>",
 //   "=": "<function>",
 //   "!=": "<function>",
 //   "<": "<function>",
 //   "<=": "<function>",
 //   ">=": "<function>",
 //   ">": "<function>",
+//   "T": true,
+//   "F": false,
+//   "null": null,
 //   "and": "<function>",
 //   "or": "<function>",
 //   "not": "<function>",
@@ -263,13 +385,15 @@ evalSource(SRC, {...ENV, name: "lispy"});
 //   "rad": "<function>",
 //   "step": "<function>",
 //   "smoothstep": "<function>",
-//   "aget": "<function>",
-//   "aset": "<function>",
+//   "get": "<function>",
+//   "set!": "<function>",
 //   "push": "<function>",
 //   "concat": "<function>",
 //   "count": "<function>",
 //   "first": "<function>",
 //   "next": "<function>",
+//   "str": "<function>",
+//   "join": "<function>",
 //   "lower": "<function>",
 //   "upper": "<function>",
 //   "capitalize": "<function>",
@@ -281,15 +405,22 @@ evalSource(SRC, {...ENV, name: "lispy"});
 //   "re-test": "<function>",
 //   "re-match": "<function>",
 //   "replace": "<function>",
+//   "identity": "<function>",
+//   "always": "<function>",
+//   "never": "<function>",
+//   "int": "<function>",
+//   "float": "<function>",
 //   "print": "<function>",
-//   "env": "<function>",
 //   "partial": "<function>",
 //   "partial2": "<function>",
 //   "comp": "<function>",
 //   "comp2": "<function>",
+//   "fnull?": "<function>",
 //   "reduce": "<function>",
 //   "map": "<function>",
-//   "filter": "<function>"
+//   "filter": "<function>",
+//   "name": "lispy",
+//   "greetings!": "<function>"
 // }
 ```
 
@@ -304,10 +435,10 @@ If this project contributes to an academic publication, please cite it as:
   title = "@thi.ng/lispy",
   author = "Karsten Schmidt",
   note = "https://thi.ng/lispy",
-  year = 2025
+  year = 2023
 }
 ```
 
 ## License
 
-&copy; 2025 Karsten Schmidt // Apache License 2.0
+&copy; 2023 - 2025 Karsten Schmidt // Apache License 2.0

package/index.d.ts

@@ -7,9 +7,9 @@ export type Env = Record<string, any>;
  */
 export declare const BUILTINS: import("@thi.ng/defmulti").MultiFn2<ASTNode[], Env, any>;
 /**
- * Root environment bindings. This is the default env used by
- * {@link evalExpressions} and can be used to define extensions of the core
- * language. Functions defined here can receive any number of arguments.
+ * Root environment bindings. This is the default env used by {@link evalSource}
+ * and can be used to define extensions of the core language. Functions defined
+ * here can receive any number of arguments.
  */
 export declare const ENV: Env;
 /**

package/index.js

@@ -1,3 +1,4 @@
+import { identity, always, never } from "@thi.ng/api/fn";
 import { isFunction } from "@thi.ng/checks/is-function";
 import { OPERATORS } from "@thi.ng/compare/ops";
 import { DEFAULT, defmulti } from "@thi.ng/defmulti";
@@ -33,6 +34,36 @@ const __fnImpl = (args, body, env) => (...xs) => {
   );
   return body.reduce((_, x) => interpret(x, $env), void 0);
 };
+const __threadOp = (fn) => ([_, ...body], env) => {
+  const n = body.length;
+  if (!n) return;
+  let res = body[0];
+  for (let i = 1; i < n; i++) {
+    const curr = { ...body[i] };
+    assert(
+      curr.type === "expr",
+      `expected expression, got ${curr.type}`
+    );
+    const $curr = curr;
+    $curr.children = fn(res, $curr.children);
+    res = $curr;
+  }
+  return interpret(res, env);
+};
+const __injectBindings = (args, env) => {
+  const pairs = args.children;
+  assert(
+    args.type === "expr" && !(pairs.length % 2),
+    `require pairs of key-val bindings`
+  );
+  for (let i = 0, n = pairs.length; i < n; i += 2) {
+    assert(
+      pairs[i].type === "sym",
+      `expected symbol, got: ${pairs[i].type}`
+    );
+    env[pairs[i].value] = interpret(pairs[i + 1], env);
+  }
+};
 const BUILTINS = defmulti(
   (x) => x[0].value,
   {},
@@ -52,22 +83,40 @@ const BUILTINS = defmulti(
     // create local symbol/variable bindings, e.g.
     // `(let (a 1 b 2 c (+ a b)) (print a b c))`
     let: ([_, args, ...body], env) => {
-      const pairs = args.children;
-      assert(
-        args.type === "expr" && !(pairs.length % 2),
-        `require pairs of key-val bindings`
-      );
-      let $env = { ...env };
-      for (let i = 0, n = pairs.length; i < n; i += 2) {
-        assert(
-          pairs[i].type === "sym",
-          `expected symbol, got: ${pairs[i].type}`
-        );
-        $env[pairs[i].value] = interpret(pairs[i + 1], $env);
-      }
+      const $env = { ...env };
+      __injectBindings(args, $env);
       return body.reduce((_2, x) => interpret(x, $env), void 0);
     },
+    while: ([, test, ...body], env) => {
+      const n = body.length;
+      while (interpret(test, env)) {
+        for (let i = 0; i < n; i++) interpret(body[i], env);
+      }
+    },
+    "env!": ([_, args], env) => __injectBindings(args, env),
     list: ([_, ...body], env) => evalArgs(body, env),
+    obj: ([_, ...body], env) => {
+      assert(!(body.length % 2), `require pairs of key-val bindings`);
+      const obj = {};
+      for (let i = 0, n = body.length; i < n; i += 2) {
+        const key = body[i].type === "expr" ? interpret(body[i], env) : body[i].value;
+        obj[String(key)] = interpret(body[i + 1], env);
+      }
+      return obj;
+    },
+    // rewriting operators:
+    // iteratively threads first child as FIRST arg of next child
+    // (-> a (+ b) (* c)) = (* (+ a b) c)
+    "->": __threadOp((res, [f, ...children]) => [f, res, ...children]),
+    // iteratively threads first child as LAST arg of next child
+    // (->> a (+ b) (* c)) = (* c (+ b a))
+    "->>": __threadOp((res, children) => [...children, res]),
+    env: (_, env) => JSON.stringify(
+      env,
+      (_2, val) => isFunction(val) ? "<function>" : val,
+      2
+    ),
+    syms: (_, env) => Object.keys(env),
     // add default/fallback implementation to allow calling functions defined in
     // the environment (either externally or via `defn`)
     [DEFAULT]: ([x, ...args], env) => {
@@ -88,11 +137,33 @@ const ENV = {
   "-": __mathOp((acc, x) => acc - x, (x) => -x),
   // prettier-ignore
   "/": __mathOp((acc, x) => acc / x, (x) => 1 / x),
+  inc: (x) => x + 1,
+  dec: (x) => x - 1,
+  // predicates
+  "null?": (x) => x == null,
+  "zero?": (x) => x === 0,
+  "neg?": (x) => x < 0,
+  "pos?": (x) => x > 0,
+  "nan?": (x) => isNaN(x),
   // comparisons
   ...OPERATORS,
   // boolean logic
-  and: (...args) => args.every((x) => !!x),
-  or: (...args) => args.some((x) => !!x),
+  T: true,
+  F: false,
+  null: null,
+  and: (...args) => {
+    let x;
+    for (x of args) {
+      if (!x) return false;
+    }
+    return x;
+  },
+  or: (...args) => {
+    for (let x of args) {
+      if (x) return x;
+    }
+    return false;
+  },
   not: (x) => !x,
   // binary
   "<<": (x, y) => x << y,
@@ -157,9 +228,9 @@ const ENV = {
   rad,
   step,
   smoothstep: smoothStep,
-  aget: (arr, i) => arr[i],
-  aset: (arr, i, x) => arr[i] = x,
-  push: (list, ...x) => list.push(...x),
+  get: (arr, i) => arr[i],
+  "set!": (arr, i, x) => arr[i] = x,
+  push: (list, ...x) => (list.push(...x), list),
   concat: (list, ...x) => list.concat(...x),
   // returns length of first argument (presumably a list or string)
   // (e.g. `(count "abc")` => 3)
@@ -170,6 +241,8 @@ const ENV = {
   // there're no further items
   next: (arg) => arg.length > 1 ? arg.slice(1) : void 0,
   // strings
+  str: (...args) => args.join(""),
+  join: (sep, args) => args.join(sep),
   lower,
   upper,
   capitalize,
@@ -181,13 +254,14 @@ const ENV = {
   "re-test": (regexp, x) => regexp.test(x),
   "re-match": (regexp, x) => regexp.exec(x),
   replace: (x, regexp, replacement) => x.replace(regexp, replacement),
+  // functions
+  identity,
+  always,
+  never,
+  int: parseInt,
+  float: parseFloat,
   // misc
-  print: console.log,
-  env: () => JSON.stringify(
-    ENV,
-    (_, val) => isFunction(val) ? "<function>" : val,
-    2
-  )
+  print: console.log
 };
 const evalSource = (src, env = ENV) => parse(src).children.reduce((_, x) => interpret(x, env), void 0);
 const evalArgs = (nodes, env = ENV) => nodes.map((a) => interpret(a, env));

package/kernel.d.ts

@@ -1,2 +1,2 @@
-export declare const KERNEL = "\n; partial functional application (currying for 1 arg)\n(defn partial (f x) (fn (y) (f x y)))\n\n; partial functional application (currying for 2 args)\n(defn partial2 (f x y) (fn (z) (f x y z)))\n\n; functional composition for 1-arg fns\n(defn comp (f g) (fn (x) (f (g x))))\n\n; functional composition for 2-arg fns\n(defn comp2 (f g) (fn (x y z) (f (g x y) z)))\n\n; list reduction\n(defn reduce (f acc xs) (if xs (reduce f (f acc (first xs)) (next xs)) acc))\n\n; list transformation (expressed as reduction)\n(defn map (f xs) (reduce (fn (acc x) (concat acc (f x))) (list) xs))\n\n; filter list with predicate function\n(defn filter (f xs) (reduce (fn (acc x) (if (f x) (concat acc x) acc)) (list) xs))\n";
+export declare const KERNEL = "\n; partial functional application (currying for 1 arg)\n(defn partial (f x) (fn (y) (f x y)))\n\n; partial functional application (currying for 2 args)\n(defn partial2 (f x y) (fn (z) (f x y z)))\n\n; functional composition for 1-arg fns\n(defn comp (f g) (fn (x) (f (g x))))\n\n; functional composition for 2-arg fns\n(defn comp2 (f g) (fn (x y z) (f (g x y) z)))\n\n; calls f if x is nullish\n(defn fnull? (x f) (if (null? x) (f) x))\n\n; list reduction\n(defn reduce (f acc xs) (if xs (reduce f (f acc (first xs)) (next xs)) acc))\n\n; list transformation (expressed as reduction)\n(defn map (f xs) (reduce (fn (acc x) (concat acc (f x))) (list) xs))\n\n; filter list with predicate function\n(defn filter (f xs) (reduce (fn (acc x) (if (f x) (concat acc x) acc)) (list) xs))\n";
 //# sourceMappingURL=kernel.d.ts.map

package/kernel.js

@@ -11,6 +11,9 @@ const KERNEL = `
 ; functional composition for 2-arg fns
 (defn comp2 (f g) (fn (x y z) (f (g x y) z)))
 
+; calls f if x is nullish
+(defn fnull? (x f) (if (null? x) (f) x))
+
 ; list reduction
 (defn reduce (f acc xs) (if xs (reduce f (f acc (first xs)) (next xs)) acc))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/lispy",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight, extensible, interpreted Lisp-style DSL for embedding in other projects",
   "type": "module",
   "module": "./index.js",
@@ -46,7 +46,7 @@
     "@thi.ng/errors": "^2.5.33",
     "@thi.ng/math": "^5.11.27",
     "@thi.ng/object-utils": "^1.1.23",
-    "@thi.ng/sexpr": "^1.0.16",
+    "@thi.ng/sexpr": "^1.0.17",
     "@thi.ng/strings": "^3.9.12"
   },
   "devDependencies": {
@@ -55,6 +55,19 @@
     "typescript": "^5.8.3"
   },
   "keywords": [
+    "array",
+    "clojure",
+    "composition",
+    "dsl",
+    "functional",
+    "interpreter",
+    "language",
+    "lisp",
+    "parser",
+    "regexp",
+    "runtime",
+    "s-expression",
+    "string",
     "typescript"
   ],
   "publishConfig": {
@@ -80,8 +93,8 @@
     }
   },
   "thi.ng": {
-    "status": "alpha",
-    "year": 2025
+    "status": "beta",
+    "year": 2023
   },
-  "gitHead": "90ae29324123738dde721193785a6743cdf4181e\n"
+  "gitHead": "0108278642f57ca9fc7bed0edc967991c20cd594\n"
 }