Add support for operator overloading

Author: jstrieb

README.md

@@ -221,6 +221,95 @@ functions.time = function() {
 
 </details>
 
+### Operator Overloading
+
+<details>
+
+<summary>Click to read about operator overloading</summary>
+
+In Code Grid formulas, infix operators (such as `+`) are compatible with the
+same types as the corresponding JavaScript operator. For example, it is equally
+valid to do `"x" + "y"` or `3 + 2` in formulas, since addition works on both
+strings and numbers in JavaScript. Using the same infix operator (`+`) for
+different operations on different types is called "operator overloading."
+
+Code Grid allows users to extend infix operations to work on more complex types
+through advanced operator overloading. To make a type use a custom operation for
+an infix operator, define a method with the same name as that operator. That's
+it. For binary operations, the implementing method should take one argument. For
+unary operations, the method should take no arguments.
+
+For example, we could implement vectors that support element-wise addition:
+
+``` javascript
+class Vector {
+  constructor(a) {
+    this.elements = a;
+  }
+  
+  toString() {
+    return "<" + this.elements.join(", ") + ">";
+  }
+  
+  ["+"](v) {
+    return new Vector(this.elements.map((x, i) => x + v.elements[i]));
+  }
+}
+
+functions.v = (...a) => new Vector(a);
+```
+
+Then, the following would be a valid Code Grid formula that would evaluate to
+`<1, 2, 3>`, even though adding vector objects in JavaScript would throw an
+error:
+
+```
+=v(0, 3, 1) + v(1, -1, 2)
+```
+
+We could also implement overloading of the unary `~` operator to switch the sign
+of all vector elements by adding the following method to the `Vector` class:
+
+``` javascript
+class Vector {
+  // ...
+
+  // ~<1, -1, 3> => <-1, 1, -3>
+  ["~"]() {
+    return new Vector(this.elements.map(x => -x));
+  }
+
+  // ...
+}
+```
+
+Consider operations between different types. For example, if we want to
+implement vector-scalar subtraction, we will need to handle `<vector> - scalar`
+as well as `scalar - <vector>`. 
+
+When evaluating an infix operation `x op y`, Code Grid first tries `x.op(y)`,
+then `x.op.forward(y)`, then `y.op.backward(x)`, finally falling back on the
+default operator implementation if nothing else works. In this example, we will
+implement `<vector> - scalar` in the `forward` method, and `scalar - <vector>`
+in the `backward` method:
+
+``` javascript
+class Vector {
+  // ...
+
+  ["-"] = {
+    // <v> - s
+    forward: (s) => new Vector(this.elements.map(x => x - s));
+    // s - <v>
+    backward: (s) => new Vector(this.elements.map(x => s - x));
+  }
+
+  // ...
+}
+```
+
+</details>
+
 # How Code Grid Works
 
 ## Code Table of Contents

src/formula.js

@@ -114,7 +114,15 @@ class BinaryOperation extends Expression {
         .forEach((op) => {
           const x = args.shift();
           const y = args.shift();
-          args.unshift(BinaryOperation.operations[op](x, y));
+          if (typeof x[op] === "function") {
+            args.unshift(x[op](y));
+          } else if (typeof x[op]?.forward === "function") {
+            args.unshift(x[op].forward(y));
+          } else if (typeof y[op]?.reverse === "function") {
+            args.unshift(y[op].reverse(x));
+          } else {
+            args.unshift(BinaryOperation.operations[op](x, y));
+          }
         });
       // Note that args is a singleton list
       return args;
@@ -137,12 +145,18 @@ class UnaryOperation extends Expression {
 
   constructor(operator, operand) {
     super();
-    this.operator = UnaryOperation.operations[operator];
+    this.operator = operator;
     this.operand = operand;
   }
 
   compute(globals, sheet, r, c) {
-    const thunk = (x) => [this.operator(x)];
+    const thunk = (x) => {
+      if (typeof x[this.operator] === "function") {
+        return [x[this.operator]()];
+      } else {
+        return [UnaryOperation.operations[this.operator](x)];
+      }
+    };
     const refs = [this.operand.compute(globals, sheet, r, c)];
     return new ExpressionValue(undefinedArgsToIdentity(thunk), refs);
   }

test/sheet-and-formula.test.js

@@ -568,3 +568,79 @@ test("Delete columns in the middle of a sheet", async () => {
     [7, 9, 16],
   ]);
 });
+
+test("Operator overloading", async () => {
+  evalCode(`
+    class Vector {
+      constructor(a) {
+        this.elements = a;
+        this["+"].reverse = (x) => this["+"](x);
+      }
+      
+      toString() {
+        return "<" + this.elements.join(", ") + ">";
+      }
+      
+      ["*"](v) {
+        return this.elements
+          .map((x, i) => x * v.elements[i])
+          .reduce((a, x) => a + x, 0);
+      }
+      
+      ["+"](s) {
+        return new Vector(this.elements.map(x => x + s));
+      }
+      
+      ["-"] = {
+        forward: (s) => new Vector(this.elements.map(x => x - s)),
+        backward: (s) => new Vector(this.elements.map(x => s - x)),
+      }
+    }
+
+    functions.v = (...a) => new Vector(a);
+  `);
+  const state = createSheet([
+    ["=V(1, 2, 3)", "=v(4, 5, 7)", "=RC0 * RC1"],
+    ["=5 + R[-1]C + -2", "=R[-1]C - 5 - -1", undefined],
+  ]);
+  let expected = [
+    ["<1, 2, 3>", "<4, 5, 7>", "35"],
+    ["<7, 8, 10>", "<0, 1, 3>", undefined],
+  ];
+  await Promise.all(
+    expected
+      .map((row, i) =>
+        row.map((cell, j) =>
+          expect
+            .poll(() => state.currentSheet.cells[i][j].get()?.toString())
+            .toEqual(cell),
+        ),
+      )
+      .flat(),
+  );
+});
+
+test("Operator overloading with monkeypatching", async () => {
+  evalCode(`
+    String.prototype["*"] = function(n) {
+      return this.repeat(n);
+    }
+
+    Number.prototype["*"] = function(s) {
+      return s?.repeat?.(this);
+    }
+
+    String.prototype["~"] = function() {
+      return this
+        .split("")
+        .map(x => x == x.toLocaleUpperCase() 
+          ? x.toLocaleLowerCase() 
+          : x.toLocaleUpperCase()
+        ).join("");
+    }
+  `);
+  const state = createSheet([[`="test " * 3`, `=3 * RC[-1]`, `=~~~"TeSt"`]]);
+  await expectSheet(state.currentSheet, [
+    ["test ".repeat(3), "test ".repeat(9), "tEsT"],
+  ]);
+});