Merge pull request #8 from Rhea-OS/documentation

J-Cake · web-flow · commit 767224659452 · 2025-04-25T17:56:44.000+02:00
Documentation
diff --git a/expression-js/build.js b/expression-js/build.js
@@ -3,56 +3,48 @@ import cp from "node:child_process";
 import {esbuild} from 'builder';
 
 export default {
-    async "build:main.wasm"(config) {
-        const out = config.out.join("mod");
-        const wasmPack = cp.spawn('wasm-pack', [
-            'build',
-            '--out-dir',
-            out.path,
-        ], {
-            stdio: "inherit"
-        });
-        await new Promise((ok, err) => wasmPack.once("exit", code => code === 0 ? ok() : err(code)));
-    },
-    async "build:main.js"(config) {
-        await esbuild.build({
-            entryPoints: ["lib.ts"],
-            bundle: true,
-            sourcemap: true,
-            format: 'esm',
-            loader: {
-                ".wasm": "binary"
-            },
-            outdir: config.out.join("pkg").path
-        });
-    },
-    async "build:lib.d.ts"(config) {
-        await fs.copyFile(config.out.join("mod/expression_js.d.ts").path, config.out.join("pkg/lib.d.ts").path);
-    },
-    async "build:package.json"(config) {
-        await fs.writeFile(config.out.join("pkg/package.json").path, JSON.stringify({
-            name: "expression",
-            type: "module",
-            main: "./lib.js",
-            typings: "./lib.d.ts"
-        }, null, 4));
-    },
-    async "test:lib.js"(config) {
-        const file = config.out.join("lib.js");
-        /**
-         * @type {typeof import('./build/mod/expression_js.d.ts')}
-         */
-        const mod = await import(file.path).then(mod => mod.default());
+	async "build:main.wasm"(config) {
+		const out = config.out.join("mod");
+		const wasmPack = cp.spawn('wasm-pack', [
+			'build',
+			'--out-dir',
+			out.path,
+		], {
+			stdio: "inherit"
+		});
+		await new Promise((ok, err) => wasmPack.once("exit", code => code === 0 ? ok() : err(code)));
+	},
+	async "build:main.js"(config) {
+		await esbuild.build({
+			entryPoints: ["lib.ts"],
+			bundle: true,
+			sourcemap: true,
+			format: 'esm',
+			loader: {
+				".wasm": "binary"
+			},
+			outdir: config.out.join("pkg").path
+		});
+	},
+	async "build:lib.d.ts"(config) {
+		const lib = await fs.readFile('./lib.d.ts', {encoding: 'utf8'});
+		const mod = await fs.readFile(config.out.join("mod/expression_js.d.ts").path, {encoding: 'utf8'});
 
-        const cx = new mod.Context(new mod.DataSource({
-            listRows: () => [],
-            listColumns: () => [],
-            countRows: () => 0,
-            getRow: row => void 0
-        }));
+		await fs.writeFile(config.out.join("pkg/expr.d.ts").path, mod);
 
-        cx.pushGlobal("x", "Hello")
-
-        console.log(cx.evaluate(`x+x`));
-    }
+		await fs.writeFile(config.out.join("pkg/lib.d.ts").path, lib
+			.replaceAll(lib.match(/( {2,})/)[0], '\t')
+			.replaceAll(/\n{2,}/g, '\n'));
+	},
+	async "build:package.json"(config) {
+		await fs.writeFile(config.out.join("pkg/package.json").path, JSON.stringify({
+			name: "expression",
+			type: "module",
+			main: "./lib.js",
+			typings: "./lib.d.ts"
+		}, null, 4));
+	},
+	async "build:readme.md"(config) {
+		await fs.writeFile(config.out.join('pkg/README.md'), await fs.readFile('./dist.md', {encoding: 'utf8'}));
+	}
 }
diff --git a/expression-js/dist.md b/expression-js/dist.md
@@ -0,0 +1,46 @@
+# expressions
+
+Parser for the expression language used in the spreadsheet plugin. This document outlines the JavaScript portion of the
+library. For Rust see [the Rust crate](../README.md).
+
+## Quickstart
+
+In order to evaluate expressions, three things must happen;
+
+1. A context object containing a [Data Provider](#Data Provider) must be registered
+2. The list of all functions, variables and operators needs to be defined
+3. The expression needs to be passed into the parser.
+
+## Data Provider
+
+A data provider is an object which converts addresses into values. Addresses are arbitrary text tokens wrapped in
+braces. The provider determines their meaning. [See the `repl.ts`](examples/repl.ts) for a feature-complete REPL.
+
+```typescript
+import * as expr from 'expression';
+
+class Table implements expr.DataSource {
+    query(cx:any, query:string) {
+        // Parse the query however you need to.
+        // For example, the format `column:row`
+
+        return "Hey!";
+    }
+}
+```
+
+## Context
+
+Next you'll need a context object which holds state and variables and acts as an API to the expression engine. You can
+define your own functions, globals and operators here.
+
+```typescript
+import * as assert from 'node:assert';
+import * as expr from 'expression';
+
+const cx = new expr.Context(new Table())
+    .withGlobal("twelve", 12)
+    .withGlobal("print", args => console.log(args));
+
+assert.eq(cx.evaluateStr("twelve") == 12);
+```
diff --git a/expression-js/examples/repl.ts b/expression-js/examples/repl.ts
@@ -0,0 +1,68 @@
+import * as rl from 'node:readline/promises';
+import * as expr from 'expression';
+
+class Table implements expr.DataSource {
+    public readonly columns: string[] = [];
+    private data: any[] = [];
+
+    constructor(columns: string[] = []) {
+        this.columns = columns;
+    }
+
+    query(cx: any, query: string) {
+        const [, col, row] = query.match(/^(.+):(\d+)$/) ?? [];
+        return this.data[Number(row) * this.columns.length + this.columns.indexOf(col)] ?? null;
+    }
+
+    set(address: string, value: any) {
+        const [, col, row] = address.match(/^(.+):(\d+)$/) ?? [];
+        this.data[Number(row) * this.columns.length + this.columns.indexOf(col)] = value;
+    }
+}
+
+const cx = new expr.Context(new Table(["a", "b", "c"]));
+const prompt = rl.createInterface(process.stdin, process.stderr);
+
+const commands = {
+    async set(address: string) {
+        const body = await prompt.question('--> ');
+        cx.provider().set(address, cx.evaluateStr(body, {}));
+    },
+
+    async func(args: string) {
+        const [name, ...params] = args.split(/\s+/);
+        const body = await prompt.question('--> ');
+        cx.pushGlobal(name, function(args: any[]) {
+            const inner = cx.clone();
+
+            for (const [a, arg] of params.entries())
+                inner.pushGlobal(arg, args[a]);
+
+            return inner.evaluateStr(body, {});
+        });
+    },
+
+    async glob(name) {
+        const body = await prompt.question('--> ');
+        cx.pushGlobal(name, cx.evaluateStr(body, {}));
+    }
+} satisfies Record<string, (arg: string) => Promise<void>>;
+
+while (true) {
+    const cmd = await prompt.question('> ').then(res => res.trim());
+
+    if (cmd === '')
+        continue;
+    else if (cmd === '/exit')
+        break;
+    else if (cmd === '/dump')
+        console.log(cx.provider());
+    else if (cmd.startsWith('/set '))
+        await commands.set(cmd.slice(5).trim());
+    else if (cmd.startsWith('/func '))
+        await commands.func(cmd.slice(6).trim());
+    else if (cmd.startsWith('/glob '))
+        await commands.glob(cmd.slice(6).trim());
+    else
+        console.log(cx.evaluateStr(cmd, {}));
+}
diff --git a/expression-js/lib.d.ts b/expression-js/lib.d.ts
@@ -0,0 +1,47 @@
+declare module 'expression' {
+    enum TokenType {
+        Name = 0,
+        Operator = 1,
+        LParen = 2,
+        LBracket = 3,
+        LBrace = 4,
+        RParen = 5,
+        RBracket = 6,
+        RBrace = 7,
+        Dot = 8,
+        Comma = 9,
+        Nothing = 10,
+        Num = 11,
+        String = 12,
+        Bool = 13,
+        Address = 14,
+    }
+
+    class Token {
+        token(): string;
+        type: TokenType
+    }
+
+    class Operator {
+        constructor(token: string, handler: (...operands: any[]) => any);
+    }
+
+    class Context<Provider extends DataSource> {
+        constructor(provider: Provider);
+        provider(): Provider;
+        clone(): Context<Provider>;
+
+        pushGlobal(name: string, value: any): void;
+        withGlobal(name: string, value: any): Context<Provider>;
+
+        pushOperator(name: string, operator: Operator): void;
+        withOperator(name: string, operator: Operator): Context<Provider>;
+
+        evaluateStr(expr: string, cx: any): any;
+        parseStr(expr: string): Token[];
+    }
+
+    interface DataSource {
+        query(cx: any, query: string): any;
+    }
+}
diff --git a/expression-js/package.json b/expression-js/package.json
@@ -11,7 +11,8 @@
         "builder": "link:../../../builder",
         "chalk": "latest",
         "typescript": "latest",
-        "esbuild-plugin-d.ts": "latest"
+        "esbuild-plugin-d.ts": "latest",
+        "expression": "link:./build/pkg"
     },
     "imports": {
         "#mod/main.wasm": "./build/mod/expression_js_bg.wasm",
@@ -20,6 +21,10 @@
     "deploy": {
         "main": "run.js",
         "imports": {},
+        "exports": {
+            "default": "./lib.js",
+            "types": "./lib.d.ts"
+        },
         "scripts": null
     }
 }
diff --git a/expression-js/src/context.rs b/expression-js/src/context.rs
@@ -43,7 +43,7 @@ pub(crate) fn js_value_to_object(value: JsValue) -> Option<Object> {
         
         value if value.is_function() => {
             let value = value.clone();
-            Object::Function(Rc::new(Box::new(move |args| {
+            Object::function(move |args| {
                 let args = js_sys::Array::from_iter(args.into_iter()
                     .map(value_to_js_object)
                     .map(|i| i.ok_or(Into::<Error>::into(ManualError::ConversionFailed)))
@@ -53,7 +53,7 @@ pub(crate) fn js_value_to_object(value: JsValue) -> Option<Object> {
                     .unwrap_throw();
                 js_value_to_object(result)
                     .ok_or(ManualError::ConversionFailed.into())
-            })))
+            })
         },
 
         // TODO: Detect Addresses
@@ -117,15 +117,15 @@ pub(crate) fn value_to_js_object(value: Object) -> Option<JsValue> {
 #[wasm_bindgen(js_class=Context)]
 impl Context {
     #[wasm_bindgen(constructor)]
-    pub fn new(config: DataSource) -> Context {
-        let cx = config.cx.clone();
+    pub fn new(config: js_sys::Object) -> Context {
+        let cx = DataSource::from_js(config);
 
         Self {
-            global_context: cx.clone(),
-            cx: expression::Context::new(config)
-                .with_global("cx", Object::function(move |_| {
-                    Ok(cx.borrow().clone())
-                })),
+            global_context: cx.cx.clone(),
+            cx: expression::Context::new(cx)
+                .with_fn("cx", move |cx, _| {
+                    Ok(cx.provider().cx.borrow().clone())
+                })
         }
     }
 
@@ -211,6 +211,8 @@ impl Context {
                 },
                 Value::Expression(parse::expression::Expression { operator, .. }) => Some(vec![Token::new(operator.clone(), TokenType::Operator)]),
                 Value::Literal(lit) => Some(vec![match lit {
+                    Literal::Nothing => Token::new("nothing".to_owned(), TokenType::Nothing),
+                    Literal::Bool(bool) => Token::new(format!("{}", bool), TokenType::Bool),
                     Literal::Name(name) => Token::new(name.clone(), TokenType::Name),
                     Literal::String(str) => Token::new(str.clone(), TokenType::String),
                     Literal::Number(num) => Token::new(format!("{}", num), TokenType::Num),
@@ -238,6 +240,19 @@ impl Context {
             Err(err) => wasm_bindgen::throw_str(&format!("{:#?}", err))
         }).unwrap_or(vec![])
     }
+
+    #[wasm_bindgen(js_name="clone")]
+    pub fn clone(&self) -> Self {
+        Self {
+            cx: self.cx.clone(),
+            global_context: self.global_context.clone(),
+        }
+    }
+
+    #[wasm_bindgen(js_name="provider")]
+    pub fn provider(&self) -> JsValue {
+        self.cx.provider().inner.clone().into()
+    }
 }
 
 #[wasm_bindgen]
@@ -259,8 +274,6 @@ pub struct Token {
     #[wasm_bindgen(js_name="type")]
     pub token_type: TokenType,
     token: String,
-//    #[wasm_bindgen(js_name="tokenOffset")]
-//    pub token_start: usize,
 }
 
 #[wasm_bindgen]
@@ -293,6 +306,7 @@ pub enum TokenType {
     RBrace,
     Dot,
     Comma,
+    Nothing,
     Num,
     String,
     Bool,
diff --git a/expression-js/src/datasource.rs b/expression-js/src/datasource.rs
diff --git a/expression-js/tsconfig.json b/expression-js/tsconfig.json
