@tilua/compiler 5.0.0 → 6.0.0

package/README.md

@@ -75,6 +75,14 @@ JavaScript module the build loads.
 | `for (const item in xs)` | `for _, item in xs do … end` — an array or a table walked for its values |
 | `for (const item in step)` | `for item in step do … end` — an iterator function |
 | `for (const [k, v] in pairs(t))` | `for item in unpack(pairs(t), 1, 3) do local k, v = item[1], item[2] … end` — an iteration is `[step, state, first]` |
+| `t ??= v` | `if t == nil then t = v end` — what addresses `t` read once, into locals |
+| `{ m() { … } }` | `{ m = function(this) … end }` — called with `:` |
+| `break outer` from a loop inside `outer` | a flag `outer` declares, raised, and a `break`; after each loop on the way out, a check that breaks again — or, at `outer`, does the `break` or `continue` |
+| `throw value` | `error(value, 0)` — level 0, so a `catch` is handed exactly what was thrown |
+| `try { a } catch (e) { b }` | `local ok, result = pcall(function() a end) if not ok then local e = result b end` |
+| `try { a } catch (e) { b } finally { c }` | `a` and then `b` each in a `pcall`, `c` after them, and what neither caught thrown again |
+| a `return`, `break` or `continue` that leaves a `try` | its function returns a code — and the value — and an `if` after the `pcall` does the jump there |
+| code after a `return`, `break` or `continue` | left out: Luau allows nothing after one in its block |
 | `pcall(f)`, and other globals Luau answers several values from | the type library's own function, answering one — see below |
 | `function f(a, ...rest)` | `function f(a, ...) local rest = {...}` |
 | `scriptArgs` | the chunk's own `...`, as `local scriptArgs = { ... }` |
@@ -83,6 +91,8 @@ JavaScript module the build loads.
 | `import("./shop")` | `G.import("src/shop")` — the bundle's `require`, wrapped |
 | `a ?? b` | `if a ~= nil then a else b` for a name; otherwise a function that reads `a` once |
 | `n++` / `n--` | `n += 1` / `n -= 1` |
+| `s + t`, `s += t` with a string on a side | `s .. t`, `s ..= t` |
+| `a + b` where only the values can say — `any`, `string \| number` | `tilua_add(a, b)`: joins if either is a string, else adds |
 | `"key" in t` | `(t["key"] ~= nil)` |
 | `v instanceof Dog` | `tilua_instanceof(v, Dog)` — walks `v.ClassObject`, then each `.ParentClass` |
 | `{ a: 1, get b() { … }, set b(v) { … } }` | `tilua_accessors({ a = 1 }, { b = … }, { b = … })` — a metatable runs the accessors |
@@ -180,7 +190,9 @@ another, and one the class writes itself replaces the copy.
 Two links come with every class, and they cost an instance nothing because
 they live on the class table: `ClassObject`, which an instance reads through
 its metatable to reach its own class, and `ParentClass`, which a class reads
-to reach the one it extends.
+to reach the one it extends. The class table holds its `name` too
+(`tilua_class(base, "Dog")`), so `rex.ClassObject.name` says what built an
+instance.
 
 A class written as a value (`const Counter = class { … }`) is the same code,
 inside a function that runs where the class is written and hands the table

package/dist/{chunk-3J2QMA4W.js → chunk-EQE22LX7.js}

@@ -245,7 +245,29 @@ var standardLowering = { plugin: plugin2, from: "tilua (standard library)" };
 
 // src/lower.ts
 function lower(program2, scopes, options = {}) {
-  return new Lowerer(program2, scopes, options).run();
+  const result2 = new Lowerer(program2, scopes, options).run();
+  dropUnreachable(result2.statements);
+  return result2;
+}
+function dropUnreachable(statements) {
+  const exit = statements.findIndex((s) => s.type === "ReturnStatement" || s.type === "BreakStatement" || s.type === "ContinueStatement");
+  if (exit >= 0) statements.length = exit + 1;
+  for (const statement of statements) visitBlocks(statement);
+}
+function visitBlocks(node) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const item of node) visitBlocks(item);
+    return;
+  }
+  const record = node;
+  if (record.type === "Block" && Array.isArray(record.statements)) {
+    dropUnreachable(record.statements);
+    return;
+  }
+  for (const key in record) {
+    if (key !== "line" && key !== "column") visitBlocks(record[key]);
+  }
 }
 var Lowerer = class {
   constructor(source, scopes, options) {
@@ -258,6 +280,18 @@ var Lowerer = class {
     for (const binding of scopes.bindings.values()) {
       if (binding.declarationNode) this.bindingByDeclaration.set(binding.declarationNode, binding);
     }
+    const visit = (value) => {
+      if (!value || typeof value !== "object") return;
+      if (Array.isArray(value)) return void value.forEach(visit);
+      const node = value;
+      if (node.type === "VariableDeclaration" && node.name?.type === "IdentifierPattern" && node.name.name) {
+        let init = node.init;
+        while (init?.type === "ParenthesizedExpression") init = init.expression;
+        if (init?.type === "ClassExpression") this.classExpressionNames.set(init, node.name.name);
+      }
+      for (const [key, child] of Object.entries(value)) if (key !== "line" && key !== "column") visit(child);
+    };
+    visit(source.body);
   }
   source;
   scopes;
@@ -275,10 +309,17 @@ var Lowerer = class {
   exportsName;
   /** Globals generated code calls, renamed where the source shadows them. */
   builtins = /* @__PURE__ */ new Map();
+  /** The `try` blocks being lowered in the current function, innermost
+   *  last; see `tryStatement`. A function written inside one starts afresh. */
+  tryFrames = [];
+  /** The loops being lowered in the current function, innermost last. */
+  loops = [];
   /** Whether the output has to be plain Lua 5.1 rather than Luau. */
   lua51;
   /** The source line each emitted statement came from. */
   origins = /* @__PURE__ */ new WeakMap();
+  /** The name each class written as a value is known by. */
+  classExpressionNames = /* @__PURE__ */ new WeakMap();
   run() {
     const body = this.options.module ? this.module(this.options.module) : this.topLevel(this.source.body.statements);
     const scriptArgs = this.usesScriptArgs && !this.options.module ? [local(["scriptArgs"], [this.array(table([{ type: "TableFieldPositional", value: vararg() }]))])] : [];
@@ -638,6 +679,16 @@ local function ${typeOf}(value, known)
 end`).body.statements);
       }
     }
+    const add = this.helpers.get("add");
+    if (add) {
+      out.push(...parseLuau(`
+local function ${add}(a, b)
+	if ${this.builtin("type").name}(a) == "string" or ${this.builtin("type").name}(b) == "string" then
+		return ${this.builtin("tostring").name}(a) .. ${this.builtin("tostring").name}(b)
+	end
+	return a + b
+end`).body.statements);
+    }
     const instanceOf = this.helpers.get("instanceof");
     if (instanceOf) {
       out.push(...parseLuau(`
@@ -660,6 +711,8 @@ end`).body.statements);
       out.push(...parseLuau(`
 local function ${accessors}(target, getters, setters)
 	return ${this.builtin("setmetatable").name}(target, {
+		-- Read by a spread, which copies what the getters give.
+		__tiluaGetters = getters,
 		__index = function(self, key)
 			local get = getters[key]
 			if get ~= nil then
@@ -683,17 +736,25 @@ end`).body.statements);
     }
     const assign2 = this.helpers.get("assign");
     if (assign2) {
-      out.push(localFunction(assign2, functionBody(["target"], [
-        numericFor("i", number(1), selectCount(this.builtin("select")), [
-          local(["source"], [call(this.builtin("select"), [identifier("i"), vararg()])]),
-          ifThen(binary("~=", identifier("source"), nil()), [
-            genericFor(["key", "value"], [call(this.builtin("pairs"), [identifier("source")])], [
-              assign([index(identifier("target"), identifier("key"))], [identifier("value")])
-            ])
-          ])
-        ]),
-        returns([identifier("target")])
-      ], true)));
+      out.push(...parseLuau(`
+local function ${assign2}(target, ...)
+	for i = 1, ${this.builtin("select").name}("#", ...) do
+		local source = (${this.builtin("select").name}(i, ...))
+		if source ~= nil then
+			for key, value in ${this.builtin("pairs").name}(source) do
+				target[key] = value
+			end
+			local meta = ${this.builtin("type").name}(source) == "table" and ${this.builtin("getmetatable").name}(source) or nil
+			local getters = ${this.builtin("type").name}(meta) == "table" and ${this.builtin("rawget").name}(meta, "__tiluaGetters") or nil
+			if getters ~= nil then
+				for key, get in ${this.builtin("pairs").name}(getters) do
+					target[key] = get(source)
+				end
+			end
+		end
+	end
+	return target
+end`).body.statements);
     }
     out.push(...runtimes);
     const concat = this.helpers.get("concat");
@@ -1052,7 +1113,49 @@ end`).body.statements);
     if (!this.origins.has(statement)) this.origins.set(statement, node.line.start);
     return statement;
   }
+  /** A statement; a loop with what its labels need around it.
+   *
+   *  Luau has no labels, and no `goto` to stand in for them. `break outer`
+   *  in a loop inside `outer` sets a flag `outer` declares and breaks the
+   *  loop it is in; right after that loop, the flag is checked, and the
+   *  check breaks again — or, once it is `outer` that would be left, does
+   *  what was asked of `outer` itself. `continue outer` is the same, with
+   *  `continue` done there and the flag lowered for the next time round. */
   statementOf(node) {
+    if (!LOOPS.has(node.type)) return this.statementKind(node);
+    const loop = {
+      label: node.label?.name,
+      tryDepth: this.tryFrames.length,
+      leaving: /* @__PURE__ */ new Set()
+    };
+    this.loops.push(loop);
+    let lowered;
+    try {
+      lowered = this.statementKind(node);
+    } finally {
+      this.loops.pop();
+    }
+    const flags = [loop.breakFlag, loop.continueFlag].filter((f) => f !== void 0);
+    const out = [...flags.length ? [local(flags, flags.map(() => boolean(false)))] : [], ...lowered];
+    const enclosing = this.loops[this.loops.length - 1];
+    for (const target of loop.leaving) {
+      if (target === enclosing) {
+        if (target.breakFlag) out.push(ifThen(identifier(target.breakFlag), this.jump("break", void 0)));
+        if (target.continueFlag) {
+          out.push(ifThen(identifier(target.continueFlag), [
+            assign([identifier(target.continueFlag)], [boolean(false)]),
+            ...this.jump("continue", void 0)
+          ]));
+        }
+        continue;
+      }
+      enclosing?.leaving.add(target);
+      const raised = [target.breakFlag, target.continueFlag].filter((f) => f !== void 0).map((f) => identifier(f)).reduce((a, b) => binary("or", a, b));
+      out.push(ifThen(raised, this.jump("break", void 0)));
+    }
+    return out;
+  }
+  statementKind(node) {
     switch (node.type) {
       // Types, and what exists only for them.
       case "TypeAliasStatement":
@@ -1072,15 +1175,20 @@ end`).body.statements);
         return this.classDeclaration(node, "declare");
       case "AssignmentStatement":
         return this.assignment(node);
-      case "CompoundAssignmentStatement":
-        if (this.lua51) return this.compoundAssignment51(node);
+      case "CompoundAssignmentStatement": {
+        if (node.operator === "??=") return this.nullishAssignment(node);
+        const join = node.operator === "+=" ? this.options.types?.joins.get(node) : void 0;
+        if (join === "dynamic") return this.dynamicAddition(node);
+        const operator = join === "concat" ? "..=" : node.operator;
+        if (this.lua51) return this.compoundAssignment51(node, operator);
         return [{
           type: "CompoundAssignmentStatement",
-          operator: node.operator,
+          operator,
           target: this.expression(node.target),
           value: this.expression(node.value),
           ...spanOf(node)
         }];
+      }
       case "CallStatement": {
         const chain = optionalChain(node.expression);
         if (chain) return [this.optionalCallStatement(chain)];
@@ -1166,11 +1274,20 @@ end`).body.statements);
         )];
       }
       case "ReturnStatement":
-        return [returns(node.argument ? [this.keptToOne(this.expression(node.argument))] : [])];
+        return this.jump("return", node.argument && this.keptToOne(this.expression(node.argument)), node);
       case "BreakStatement":
-        return [{ type: "BreakStatement", ...spanOf(node) }];
+        return this.jump("break", void 0, node, node.label?.name);
       case "ContinueStatement":
-        return [{ type: "ContinueStatement", ...spanOf(node) }];
+        return this.jump("continue", void 0, node, node.label?.name);
+      // Level 0: what is thrown is what a `catch` is handed, with no
+      // position put in front of a string.
+      case "ThrowStatement":
+        return [callStatement(call(
+          this.builtin("error"),
+          [this.keptToOne(this.expression(node.argument)), number(0)]
+        ))];
+      case "TryStatement":
+        return this.tryStatement(node);
       case "ImportStatement":
         if (node.isTypeOnly) return [];
         this.report(node, this.options.module ? "Imports and exports belong at the top level of a module" : "Imports and exports need a bundle: build the project with @tilua/compiler");
@@ -1183,6 +1300,90 @@ end`).body.statements);
         return [];
     }
   }
+  /** A `return`, `break` or `continue`. Inside a `try` that it leaves, it
+   *  is the `try`'s function returning a code saying which — and the value
+   *  — for the code after the `pcall` to do it there. */
+  jump(kind, value, node, label) {
+    const at = node ? spanOf(node) : {};
+    const frame = this.tryFrames[this.tryFrames.length - 1];
+    const target = kind === "return" ? void 0 : label === void 0 ? this.loops[this.loops.length - 1] : this.loops.findLast((loop) => loop.label === label);
+    if (frame && (kind === "return" || target && target.tryDepth < this.tryFrames.length)) {
+      const key = `${kind}:${label ?? ""}`;
+      let exit = frame.exits.get(key);
+      if (!exit) {
+        exit = { kind, label, code: kind === "return" ? 1 : frame.exits.size + 2 };
+        frame.exits.set(key, exit);
+      }
+      if (value) frame.returnsValue = true;
+      return [returns([number(exit.code), ...value ? [value] : []])];
+    }
+    if (kind === "return") return [{ ...returns(value ? [value] : []), ...at }];
+    const plain = () => kind === "break" ? { ...breakStatement(), ...at } : { ...breakStatement(), type: "ContinueStatement", ...at };
+    const innermost = this.loops[this.loops.length - 1];
+    if (!target || target === innermost) return [plain()];
+    const flag = kind === "break" ? target.breakFlag ??= this.names.fresh(`${target.label}Broke`) : target.continueFlag ??= this.names.fresh(`${target.label}Continued`);
+    innermost.leaving.add(target);
+    return [assign([identifier(flag)], [boolean(true)]), { ...breakStatement(), ...at }];
+  }
+  /** `try { a } catch (e) { b } finally { c }`:
+   *
+   *      local ok, result, value = pcall(function() a end)
+   *      if not ok then
+   *          ok, result, value = pcall(function(e) b end, result)
+   *      end
+   *      do c end
+   *      if not ok then error(result, 0) end
+   *      if result == 1 then return value elseif ... end
+   *
+   *  Without a `finally`, the `catch` runs in place of the second `pcall`:
+   *  nothing has to run after it. A `return`, `break` or `continue` that
+   *  leaves the `try` cannot be written inside its function; it returns a
+   *  code instead (see `jump`), and the last `if` does what it says. */
+  tryStatement(node) {
+    const ok = this.names.fresh("ok");
+    const result2 = this.names.fresh("result");
+    const value = this.names.fresh("value");
+    const frame = { exits: /* @__PURE__ */ new Map(), returnsValue: false };
+    const guarded = (block2, params, args) => {
+      this.tryFrames.push(frame);
+      let statements;
+      try {
+        statements = this.block(block2).statements;
+      } finally {
+        this.tryFrames.pop();
+      }
+      const passesVarargs = statements.some(usesVararg);
+      const func = functionExpression(functionBody(params, statements, passesVarargs));
+      return call(this.builtin("pcall"), [func, ...args, ...passesVarargs ? [vararg()] : []]);
+    };
+    const attempt = guarded(node.block, [], []);
+    const param = node.handler?.param && this.name(node.handler.param.name);
+    const inPlace = node.handler && !node.finalizer ? this.block(node.handler.body, param ? [local([param], [identifier(result2)])] : []) : void 0;
+    const caught = node.handler && node.finalizer ? guarded(node.handler.body, [param ?? "_"], [identifier(result2)]) : void 0;
+    const finalizer = node.finalizer && this.block(node.finalizer);
+    const returnsValue = frame.returnsValue;
+    const usesResult = returnsValue || frame.exits.size > 0 || !!param || !!node.finalizer;
+    const names = [ok, ...usesResult ? [result2] : [], ...returnsValue ? [value] : []];
+    const failed = () => unary("not", identifier(ok));
+    const out = [this.from(local(names, [attempt]), node)];
+    const clauses = [];
+    if (inPlace) clauses.push({ type: "IfClause", condition: failed(), body: inPlace, ...spanOf(node.handler) });
+    if (caught) out.push(ifThen(failed(), [assign(names.map(identifier), [caught])]));
+    if (finalizer) {
+      out.push(doBlock(finalizer.statements));
+      out.push(ifThen(failed(), [callStatement(call(this.builtin("error"), [identifier(result2), number(0)]))]));
+    }
+    for (const exit of [...frame.exits.values()].sort((a, b) => a.code - b.code)) {
+      clauses.push({
+        type: "IfClause",
+        condition: binary("==", identifier(result2), number(exit.code)),
+        body: block(this.jump(exit.kind, exit.kind === "return" && returnsValue ? identifier(value) : void 0, void 0, exit.label)),
+        ...spanOf(node)
+      });
+    }
+    if (clauses.length) out.push({ type: "IfStatement", clauses, ...spanOf(node) });
+    return out;
+  }
   functionDeclarationStatement(node) {
     const statement = this.functionStatement(this.reference(node.target.base), node, this.functionBody(node.func), node.isMethod, node.target.path.map((p) => p.name));
     if (!node.target.method) return statement;
@@ -1238,11 +1439,12 @@ end`).body.statements);
     const { build, accessors } = this.classHelpers;
     const metamethods = `{ ${CLASS_METAMETHODS.map((name) => `"${name}"`).join(", ")} }`;
     return parseLuau(`
-local function ${build}(base)
+local function ${build}(base, name)
     local class = { __getters = {}, __setters = {} }
     class.__index = class
     class.ClassObject = class
     class.ParentClass = base
+    class.name = name
     if base ~= nil then
         setmetatable(class, { __index = base })
         setmetatable(class.__getters, { __index = base.__getters })
@@ -1296,7 +1498,11 @@ end
    *  table is assigned to `self`, which a module has already declared. */
   classStatements(node, self, declare) {
     const { build, accessors } = this.classRuntime();
-    const create = call(identifier(build), [node.superclass ? this.reference(node.superclass) : nil()]);
+    const called = node.name?.name ?? (node.type === "ClassExpression" ? this.classExpressionNames.get(node) : void 0) ?? "";
+    const create = call(identifier(build), [
+      node.superclass ? this.reference(node.superclass) : nil(),
+      string(called)
+    ]);
     const out = [declare !== void 0 ? local([declare], [create]) : assign([self], [create])];
     const previous = this.classContext;
     this.classContext = node;
@@ -1567,6 +1773,18 @@ end
   // Functions
   // --------------------------------------------------------
   functionBody(func) {
+    const frames = this.tryFrames;
+    const loops = this.loops;
+    this.tryFrames = [];
+    this.loops = [];
+    try {
+      return this.functionBodyIn(func);
+    } finally {
+      this.tryFrames = frames;
+      this.loops = loops;
+    }
+  }
+  functionBodyIn(func) {
     const params = func.isMethod ? func.params.slice(1) : func.params;
     const prelude = [];
     const names = [];
@@ -1617,8 +1835,10 @@ end
         return nil();
       case "InterpolatedStringExpression":
         return this.interpolatedString(node);
+      // An object's method, `{ m() { ... } }`, keeps its `this` as the
+      // first parameter written out: a function value has no `:`.
       case "FunctionExpression":
-        return functionExpression(this.functionBody(node.func));
+        return functionExpression(this.classFunctionBody(node.func));
       case "TableExpression":
         return this.tableExpression(node);
       case "ArrayExpression":
@@ -1633,6 +1853,11 @@ end
         if (node.operator === "instanceof") {
           return call(this.helper("instanceof"), [this.keptToOne(left), this.keptToOne(right)]);
         }
+        if (node.operator === "+") {
+          const join = this.options.types?.joins.get(node);
+          if (join === "concat") return binary("..", left, right);
+          if (join === "dynamic") return call(this.helper("add"), [this.keptToOne(left), this.keptToOne(right)]);
+        }
         if (this.lua51 && node.operator === "//") return this.floorDivide(left, right);
         return binary(node.operator, left, right);
       }
@@ -1892,14 +2117,52 @@ end
     if (!args.length) return string(text);
     return methodCall(parenthesized(string(format)), "format", args);
   }
+  /** `t ??= v`: `if t == nil then t = v end`, which no Luau has an
+   *  operator for. `v` is read only where `t` is nil. As in `a += b` for
+   *  Lua 5.1, what addresses the target is read once: an object or key
+   *  that is not a plain name goes into a local first. */
+  nullishAssignment(node) {
+    const { before, target } = this.targetOnce(node.target);
+    const statement = ifThen(binary("==", target, nil()), [assign([target], [this.expression(node.value)])]);
+    return before.length ? [doBlock([...before, statement])] : [statement];
+  }
+  /** `t += v` where only the values can say whether it joins or adds:
+   *  `t = tilua_add(t, v)`, with what addresses `t` read once. */
+  dynamicAddition(node) {
+    const { before, target } = this.targetOnce(node.target);
+    const statement = assign([target], [call(this.helper("add"), [target, this.keptToOne(this.expression(node.value))])]);
+    return before.length ? [doBlock([...before, statement])] : [statement];
+  }
+  /** An assignment's target, as an expression that may be read and written
+   *  freely: an object or key that is not a plain name goes into a local
+   *  first, so that `t[next()]` advances once. */
+  targetOnce(node) {
+    const before = [];
+    const once = (expression, name) => {
+      if (expression.type === "Identifier" || expression.type === "StringLiteral" || expression.type === "NumberLiteral") return expression;
+      const local2 = this.names.fresh(name);
+      before.push(local([local2], [expression]));
+      return identifier(local2);
+    };
+    let target;
+    if (node.type === "MemberExpression") {
+      target = member(once(this.expression(node.object), "target"), node.property.name);
+    } else if (node.type === "IndexExpression") {
+      const object2 = once(this.expression(node.object), "target");
+      target = index(object2, once(this.expression(node.index), "key"));
+    } else {
+      target = this.expression(node);
+    }
+    return { before, target };
+  }
   /** `a += b` for Lua 5.1, which has no compound assignment: `a = a + b`.
    *
    *  The target has to be read and written, and writing it out twice would
    *  evaluate whatever addresses it twice — `t[next()] += 1` would advance
    *  twice and add to the wrong slot. So anything but a plain name has its
    *  object and key taken into locals first, and both halves use those. */
-  compoundAssignment51(node) {
-    const operator = node.operator.slice(0, -1);
+  compoundAssignment51(node, written = node.operator) {
+    const operator = written.slice(0, -1);
     const before = [];
     let target;
     if (node.target.type === "MemberExpression" || node.target.type === "IndexExpression") {
@@ -2098,6 +2361,7 @@ function optionalChain(node) {
   if (first < 0) return void 0;
   return { base: linkObject(spine[first]), links: spine.slice(first) };
 }
+var LOOPS = /* @__PURE__ */ new Set(["WhileStatement", "RepeatStatement", "NumericForStatement", "GenericForStatement"]);
 function usesVararg(node) {
   if (Array.isArray(node)) return node.some(usesVararg);
   if (!node || typeof node !== "object") return false;
@@ -2985,7 +3249,7 @@ function analyzeModules(modules, config) {
     });
     for (const d of types.diagnostics) {
       const at = d.node;
-      said.push({ file, message: d.message, line: at.line.start, column: at.column.start, category: "type" });
+      said.push({ file, message: d.message, line: at.line.start, column: at.column.start, category: "type", severity: d.severity });
     }
     const result2 = { types, diagnostics: said };
     if (partials === before) {