docs(sexpr): update readme (code example)

packages/sexpr/README.md

@@ -168,70 +168,120 @@ parse(`(* (+ 3 5) 10)`);
 
 ### Interpreter
 
-```ts
-import { Fn2 } from "@thi.ng/api";
-import { defmulti, DEFAULT } from "@thi.ng/defmulti";
-import { ASTNode, Implementations, Sym } from "@thi.ng/sexpr";
-
-// multi-dispatch fn for DSL builtins
-// we will call this function for each S-expression
-// and will delegate to the actual implementation based on
-// the expression's first item (a symbol name)
-const builtins = defmulti<Sym, ASTNode[], any>((x) => x.value);
-
-// build runtime w/ impls for all AST node types
-// the generics are the types of: the custom environment (if used)
-// and the result type(s)
-const rt = runtime<Implementations<any,any>, any, any>({
-    // delegate to builtins
+```ts tangle:export/readme.ts
+import type { Fn, Fn2 } from "@thi.ng/api";
+import { DEFAULT, defmulti, type MultiFn3 } from "@thi.ng/defmulti";
+import { assert } from "@thi.ng/errors";
+import {
+    parse,
+    runtime,
+    type ASTNode,
+    type Expression,
+    type Implementations,
+    type Sym,
+} from "@thi.ng/sexpr";
+
+// evaluator: parses given source string into an abstract syntax tree (AST) and
+// then recursively executes all resulting AST nodes using the
+// `interpret()` function defined below. Returns the result of the last node.
+const $eval = (src: string, env: any = {}) =>
+    parse(src).children.reduce((_, x) => interpret(x, env), <any>undefined);
+
+// build runtime (interpreter) w/ impls for all AST node types. the generics are
+// the types of the custom environment and the result type(s) of expressions.
+// this is a multiple-dispatch function (see thi.ng/defmulti) which chooses
+// implementations based on the AST node type
+const interpret = runtime<Implementations<any, any>, any, any>({
+    // for expression nodes (aka function calls) delegate to builtins
+    // (implementations are defined further below)
     expr: (x, env) => builtins(<Sym>x.children[0], x.children, env),
-    // lookup symbol in environment
+    // lookup symbol's value (via its name) in environment
     sym: (x, env) => env[x.value],
     // strings and numbers evaluate verbatim
     str: (x) => x.value,
-    num: (x) => x.value
+    num: (x) => x.value,
 });
 
-// helper HOF for math ops
-const op = (fn: Fn2<number, number, number>) =>
-    (_: ASTNode, vals: ASTNode[], env: any) =>
-        vals.slice(2).reduce(
-            (acc, x) => fn(acc, rt(x, env)),
-            rt(vals[1], env)
-        );
-
-// add builtins
+// another multiple-dispatch function for DSL builtins. we will call this
+// function for each S-expression node and it will delegate to the actual impl
+// based on the expression's first item (i.e. a symbol/fn name)
+const builtins: MultiFn3<Sym, ASTNode[], any, any> = defmulti((x) => x.value);
+
+// helper function which interprets all given AST nodes and returns an array of
+// their result values
+const evalArgs = (nodes: ASTNode[], env: any) => nodes.map((a) => interpret(a, env));
+
+// helper function for basic math ops variable arity.
+// with 2+ args: (+ 1 2 3 4) => 10
+// and special cases for 1 arg only, i.e.
+// `(+ 2)` => 0 + 2 => 2
+// `(- 2)` => 0 - 2 => -2
+// `(* 2)` => 1 * 2 => 2
+// `(/ 2)` => 1 / 2 => 0.5
+const mathOp =
+    (fn: Fn2<number, number, number>, fn1: Fn<number, number>) =>
+    (_: ASTNode, [__, ...args]: ASTNode[], env: any) => {
+        const first = interpret(args[0], env);
+        return args.length > 1
+            ? // use a reduction for 2+ args
+              evalArgs(args.slice(1), env).reduce((acc, x) => fn(acc, x), first)
+            : // apply special case unary function
+              fn1(first);
+    };
+
+// implementations of built-in core functions
 builtins.addAll({
-    "+": op((acc, x) => acc + x),
-    "*": op((acc, x) => acc * x),
-    "-": op((acc, x) => acc - x),
-    "/": op((acc, x) => acc / x),
-    count: (_, [__, x]) => rt(x).length
+    "+": mathOp((acc, x) => acc + x, (x) => x),
+    "*": mathOp((acc, x) => acc * x, (x) => x),
+    "-": mathOp((acc, x) => acc - x, (x) => -x),
+    "/": mathOp((acc, x) => acc / x, (x) => 1 / x),
+    // count returns the length of first argument (presumably a string)
+    // (e.g. `(count "abc")` => 3)
+    count: (_, [__, arg], env) => interpret(arg, env).length,
+    // concatenates all args into a space-separated string and prints it
+    // returns undefined
+    print: (_, [__, ...args], env) =>
+        console.log(evalArgs(args, env).join(" ")),
+    // defines as new symbol with given value, stores it in the environment and
+    // then returns the value, e.g. `(def magic 42)`
+    def: (_, [__, name, value], env) =>
+        (env[(<Sym>name).value] = interpret(value, env)),
+    // defines a new function with given name, args and body, stores it in the
+    // environment and returns it, e.g. `(defn madd (a b c) (+ (* a b) c))`
+    defn: (_, [__, name, args, ...body], env) => {
+        // create new vararg function in env
+        return (env[(<Sym>name).value] = (...xs: any[]) => {
+            // create new local env with arguments bound to named function args
+            // (i.e. simple lexical scoping)
+            const $env = (<Expression>args).children.reduce(
+                (acc, a, i) => ((acc[(<Sym>a).value] = xs[i]), acc),
+                { ...env }
+            );
+            // execute function body with local env, return result of last expr
+            return body.reduce((_, x) => interpret(x, $env), <any>undefined);
+        });
+    },
+    // add default/fallback implementation to allow calling functions defined in
+    // the environment (either externally or via `defn`)
+    [DEFAULT]: (x: ASTNode, [_, ...args]: ASTNode[], env: any) => {
+        const f = env[(<Sym>x).value];
+        assert(!!f, "missing impl");
+        return f.apply(null, evalArgs(args, env));
+    },
 });
 
-// add default/fallback implementation
-// to allow calling functions stored in environment
-builtins.add(DEFAULT, (x, [_, ...args], env) => {
-    const f = env[(<Sym>x).value];
-    assert(!!f, "missing impl");
-    return f.apply(null, args.map((a) => rt(a, env)));
-});
+// define symbol and use in another expression
+$eval(`(def chars "abc") (print (count chars) "characters")`);
+// 3 characters
 
-// evaluator
-const $eval = (src: string, env: any = {}) =>
-    rt(parse(src).children[0], env);
-
-// evaluate expression w/ given env bindings
-$eval(`(* foo (+ 1 2 3 (count "abcd")))`, { foo: 10 });
-// 100
-// i.e. 100 = 10 * (1 + 2 + 3 + 4)
-
-// call env function
-$eval(
-    `(join (+ 1 2) (* 3 4))`,
-    { join: (...xs: any[]) => xs.join(",") }
-);
-// "3,12"
+// define function (multiply-add) and test
+$eval(`(defn madd (a b c) (+ (* a b) c)) (print (madd 3 5 (* 5 2)))`);
+// 25
+
+$eval(`(print (join " | " (+ 1 2) (* 3 4) (- 5 6) (/ 7 8)))`, {
+    join: (sep: string, ...xs: any[]) => xs.join(sep),
+});
+// 3 | 12 | -1 | 0.875
 ```
 
 See

packages/sexpr/tpl.readme.md

@@ -116,70 +116,121 @@ parse(`(* (+ 3 5) 10)`);
 
 ### Interpreter
 
-```ts
-import { Fn2 } from "@thi.ng/api";
-import { defmulti, DEFAULT } from "@thi.ng/defmulti";
-import { ASTNode, Implementations, Sym } from "@thi.ng/sexpr";
-
-// multi-dispatch fn for DSL builtins
-// we will call this function for each S-expression
-// and will delegate to the actual implementation based on
-// the expression's first item (a symbol name)
-const builtins = defmulti<Sym, ASTNode[], any>((x) => x.value);
-
-// build runtime w/ impls for all AST node types
-// the generics are the types of: the custom environment (if used)
-// and the result type(s)
-const rt = runtime<Implementations<any,any>, any, any>({
-    // delegate to builtins
-    expr: (x, env) => builtins(<Sym>x.children[0], x.children, env),
-    // lookup symbol in environment
-    sym: (x, env) => env[x.value],
-    // strings and numbers evaluate verbatim
-    str: (x) => x.value,
-    num: (x) => x.value
+```ts tangle:export/readme.ts
+import type { Fn, Fn2 } from "@thi.ng/api";
+import { DEFAULT, defmulti, type MultiFn3 } from "@thi.ng/defmulti";
+import { assert } from "@thi.ng/errors";
+import {
+	parse,
+	runtime,
+	type ASTNode,
+	type Expression,
+	type Implementations,
+	type Sym,
+} from "@thi.ng/sexpr";
+
+// evaluator: parses given source string into an abstract syntax tree (AST) and
+// then recursively executes all resulting AST nodes using the
+// `interpret()` function defined below. Returns the result of the last node.
+const $eval = (src: string, env: any = {}) =>
+	parse(src).children.reduce((_, x) => interpret(x, env), <any>undefined);
+
+// build runtime (interpreter) w/ impls for all AST node types. the generics are
+// the types of the custom environment and the result type(s) of expressions.
+// this is a multiple-dispatch function (see thi.ng/defmulti) which chooses
+// implementations based on the AST node type
+const interpret = runtime<Implementations<any, any>, any, any>({
+	// for expression nodes (aka function calls) delegate to builtins
+	// (implementations are defined further below)
+	expr: (x, env) => builtins(<Sym>x.children[0], x.children, env),
+	// lookup symbol's value (via its name) in environment
+	sym: (x, env) => env[x.value],
+	// strings and numbers evaluate verbatim
+	str: (x) => x.value,
+	num: (x) => x.value,
 });
 
-// helper HOF for math ops
-const op = (fn: Fn2<number, number, number>) =>
-    (_: ASTNode, vals: ASTNode[], env: any) =>
-        vals.slice(2).reduce(
-            (acc, x) => fn(acc, rt(x, env)),
-            rt(vals[1], env)
-        );
-
-// add builtins
+// another multiple-dispatch function for DSL builtins. we will call this
+// function for each S-expression node and it will delegate to the actual impl
+// based on the expression's first item (i.e. a symbol/fn name)
+const builtins: MultiFn3<Sym, ASTNode[], any, any> = defmulti((x) => x.value);
+
+// helper function which interprets all given AST nodes and returns an array of
+// their result values
+const evalArgs = (nodes: ASTNode[], env: any) => nodes.map((a) => interpret(a, env));
+
+// helper function for basic math ops variable arity.
+// with 2+ args: (+ 1 2 3 4) => 10
+// and special cases for 1 arg only, i.e.
+// `(+ 2)` => 0 + 2 => 2
+// `(- 2)` => 0 - 2 => -2
+// `(* 2)` => 1 * 2 => 2
+// `(/ 2)` => 1 / 2 => 0.5
+const mathOp =
+	(fn: Fn2<number, number, number>, fn1: Fn<number, number>) =>
+	(_: ASTNode, [__, ...args]: ASTNode[], env: any) => {
+		const first = interpret(args[0], env);
+		return args.length > 1
+			? // use a reduction for 2+ args
+			  evalArgs(args.slice(1), env).reduce((acc, x) => fn(acc, x), first)
+			: // apply special case unary function
+			  fn1(first);
+	};
+
+// implementations of built-in core functions
 builtins.addAll({
-    "+": op((acc, x) => acc + x),
-    "*": op((acc, x) => acc * x),
-    "-": op((acc, x) => acc - x),
-    "/": op((acc, x) => acc / x),
-    count: (_, [__, x]) => rt(x).length
+	"+": mathOp((acc, x) => acc + x, (x) => x),
+	"*": mathOp((acc, x) => acc * x, (x) => x),
+	"-": mathOp((acc, x) => acc - x, (x) => -x),
+	"/": mathOp((acc, x) => acc / x, (x) => 1 / x),
+	// count returns the length of first argument (presumably a string)
+	// (e.g. `(count "abc")` => 3)
+	count: (_, [__, arg], env) => interpret(arg, env).length,
+	// concatenates all args into a space-separated string and prints it
+	// returns undefined
+	print: (_, [__, ...args], env) =>
+		console.log(evalArgs(args, env).join(" ")),
+	// defines as new symbol with given value, stores it in the environment and
+	// then returns the value, e.g. `(def magic 42)`
+	def: (_, [__, name, value], env) =>
+		(env[(<Sym>name).value] = interpret(value, env)),
+	// defines a new function with given name, args and body, stores it in the
+	// environment and returns it, e.g. `(defn madd (a b c) (+ (* a b) c))`
+	defn: (_, [__, name, args, ...body], env) => {
+		// create new vararg function in env
+		return (env[(<Sym>name).value] = (...xs: any[]) => {
+			// create new local env with arguments bound to named function args
+			// (i.e. simple lexical scoping)
+			const $env = (<Expression>args).children.reduce(
+				(acc, a, i) => ((acc[(<Sym>a).value] = xs[i]), acc),
+				{ ...env }
+			);
+			// execute function body with local env, return result of last expr
+			return body.reduce((_, x) => interpret(x, $env), <any>undefined);
+		});
+	},
+	// add default/fallback implementation to allow calling functions defined in
+	// the environment (either externally or via `defn`)
+	[DEFAULT]: (x: ASTNode, [_, ...args]: ASTNode[], env: any) => {
+		const f = env[(<Sym>x).value];
+		assert(!!f, "missing impl");
+		return f.apply(null, evalArgs(args, env));
+	},
 });
 
-// add default/fallback implementation
-// to allow calling functions stored in environment
-builtins.add(DEFAULT, (x, [_, ...args], env) => {
-    const f = env[(<Sym>x).value];
-    assert(!!f, "missing impl");
-    return f.apply(null, args.map((a) => rt(a, env)));
-});
+// define symbol and use in another expression
+$eval(`(def chars "abc") (print (count chars) "characters")`);
+// 3 characters
 
-// evaluator
-const $eval = (src: string, env: any = {}) =>
-    rt(parse(src).children[0], env);
-
-// evaluate expression w/ given env bindings
-$eval(`(* foo (+ 1 2 3 (count "abcd")))`, { foo: 10 });
-// 100
-// i.e. 100 = 10 * (1 + 2 + 3 + 4)
-
-// call env function
-$eval(
-    `(join (+ 1 2) (* 3 4))`,
-    { join: (...xs: any[]) => xs.join(",") }
-);
-// "3,12"
+// define function (multiply-add) and test
+$eval(`(defn madd (a b c) (+ (* a b) c)) (print (madd 3 5 (* 5 2)))`);
+// 25
+
+// pre-define a function in the environment and then use it
+$eval(`(print (join " | " (+ 1 2) (* 3 4) (- 5 6) (/ 7 8)))`, {
+	join: (sep: string, ...xs: any[]) => xs.join(sep),
+});
+// 3 | 12 | -1 | 0.875
 ```
 
 See