@tilua/compiler 3.0.1 → 4.0.0

package/README.md

@@ -54,9 +54,10 @@ JavaScript module the build loads.
 | tilua | Luau |
 |---|---|
 | `const { a, b } = value` | `local a, b = value.a, value.b` |
-| `const [x, ...rest] = list` | `local x = list[1]; local rest = table.move(list, 2, #list, 1, {})` |
+| `const [x, ...rest] = list` | `local x = list[1]; local rest = table.move(list, 2, #list, 1, {})` — `{}` written down as an array |
 | `const { a = 1 } = t` | `local a = t.a; if a == nil then a = 1 end` |
-| `[1, 2]` / `{ a: 1, b }` | `{ 1, 2 }` / `{ a = 1, b = b }` |
+| `[1, 2]` / `{ a: 1, b }` | `tilua_asArray({ 1, 2 })` / `{ a = 1, b = b }` — see `typeof` below |
+| `typeof v` | `tilua_typeof(v)`, or `tilua_typeof(v, "array")` where `v`'s type already says which table it is |
 | `{ ...base, a: 1 }` / `[...xs, 1]` | a small helper copying the parts in order |
 | `` `${a} any` `` | `("%s any"):format(tostring(a))` |
 | `a?.b` | `if a == nil then nil else a.b` |
@@ -77,6 +78,26 @@ JavaScript module the build loads.
 | `x as T`, `x satisfies T`, types, `declare` | removed |
 | `names:filter(f)` | whatever the type library that declared `filter` says — see below |
 
+## `typeof`, arrays and objects
+
+Luau cannot tell an array from an object: both are tables, and an empty one
+has nothing to go by. So every array the program makes is written down as
+one where it is made — `[a, b]`, a rest parameter, `scriptArgs`, what
+`:map`, `:filter`, `:keys` and the rest answer — in a table that holds its
+keys weakly, one for the whole bundle. `tilua_asArray(t)` does that and hands
+`t` back.
+
+`typeof v` is Luau's `typeof` (Lua 5.1's `type`) for anything but a table.
+For a table it answers, in order:
+
+1. what `v`'s type says, where every table it can be is an array, or every
+   one an object — passed by the compiler, so nothing is looked up;
+2. `"array"` if it was written down as one;
+3. `"object"` if it has a metatable — an instance of a class;
+4. `"array"` if it has a first element, and `"object"` otherwise: a table the
+   program did not make (one `JSONDecode` answered) is read by its shape, and
+   an empty one of those is an `"object"`.
+
 ## Classes
 
 `class` is sugar over the Lua idiom, and it lowers to that idiom and nothing
@@ -185,7 +206,7 @@ argument (`arguments`: type, the code it was written as, and what a name was
 declared as). An answer can `prepend` Luau expressions ahead of the written
 arguments. `globalCall` and `globalValue` answer for a global, such as
 `print(x)` or a bare `print`. A runtime can read `__LINES__` to reach the
-bundle's line map. See the `@tilua/parser` README for the details.
+bundle's line map, and wraps a new array it answers with in `__ARRAY__(...)`. See the `@tilua/parser` README for the details.
 `console:log` is not built into the compiler: `@tilua-types/lua` implements it
 with these hooks.
 

package/dist/{chunk-X4DM2BX2.js → chunk-VZ7XC4BG.js}

@@ -14,6 +14,7 @@ import { formatType } from "@tilua/parser";
 import { parse as parseLuau, parseExpressionFromSource } from "luau-parser";
 
 // src/luau.ts
+import { LUAU_KEYWORDS, isLuauName } from "@tilua/parser";
 var NO_SPAN = { line: { start: 0, end: 0 }, column: { start: 0, end: 0 } };
 var span = () => ({ line: { ...NO_SPAN.line }, column: { ...NO_SPAN.column } });
 var identifier = (name) => ({ type: "Identifier", name, ...span() });
@@ -74,32 +75,6 @@ var functionBody = (params, statements, hasVarargs = false) => ({
 });
 var localFunction = (name, func) => ({ type: "LocalFunctionStatement", name: identifier(name), func, ...span() });
 var program = (statements) => ({ type: "Program", body: block(statements), ...span() });
-var LUAU_KEYWORDS = /* @__PURE__ */ new Set([
-  "and",
-  "break",
-  "do",
-  "else",
-  "elseif",
-  "end",
-  "false",
-  "for",
-  "function",
-  "if",
-  "in",
-  "local",
-  "nil",
-  "not",
-  "or",
-  "repeat",
-  "return",
-  "then",
-  "true",
-  "until",
-  "while"
-]);
-function isLuauName(name) {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !LUAU_KEYWORDS.has(name);
-}
 
 // src/names.ts
 var Names = class _Names {
@@ -142,6 +117,7 @@ var Names = class _Names {
 
 // src/language.ts
 import { readFileSync } from "fs";
+import { luauString } from "@tilua/parser";
 var read = (name) => readFileSync(new URL(`../runtime/${name}`, import.meta.url), "utf8");
 var implemented = (source) => new Set([...source.matchAll(/function __NAME__\.(\w+)/g)].map((m) => m[1]));
 var array = read("array.luau");
@@ -175,7 +151,7 @@ function objectKeys(type) {
     orders.push(keys);
   }
   const order = JSON.stringify(orders[0] ?? []);
-  const known = orders.length && orders.every((keys) => JSON.stringify(keys) === order) ? `{ ${orders[0].map((key) => JSON.stringify(key)).join(", ")} }` : "nil";
+  const known = orders.length && orders.every((keys) => JSON.stringify(keys) === order) ? `{ ${orders[0].map((key) => luauString(key)).join(", ")} }` : "nil";
   return { known, open: String(open) };
 }
 var plugin = {
@@ -234,11 +210,11 @@ var Lowerer = class {
   origins = /* @__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() }]))])] : [];
     const helpers = this.helperDefinitions();
     const captured = [...this.builtins].map(([global, local2]) => local([local2], [identifier(global)]));
-    const scriptArgs = this.usesScriptArgs && !this.options.module ? [local(["scriptArgs"], [table([{ type: "TableFieldPositional", value: vararg() }])])] : [];
     return {
-      statements: [...scriptArgs, ...captured, ...helpers, ...this.classRuntimeStatements(), ...body],
+      statements: [...captured, ...helpers, ...scriptArgs, ...this.classRuntimeStatements(), ...body],
       exportsName: this.exportsName,
       module: this.info,
       diagnostics: this.diagnostics,
@@ -288,11 +264,36 @@ var Lowerer = class {
   helper(kind) {
     let name = this.helpers.get(kind);
     if (!name) {
-      name = this.names.fresh(`tilua_${kind}`);
+      name = this.names.fresh(`tilua_${kind === "array" ? "asArray" : kind}`);
       this.helpers.set(kind, name);
     }
     return identifier(name);
   }
+  // `typeof v` tells an array from an object, which Luau cannot: both are
+  // tables. So every array the program makes — `[a, b]`, a rest parameter,
+  // what `:map` answers — is written down as one, in a table that holds its
+  // keys weakly, and `typeof` looks there. A table nothing wrote down (one a
+  // Lua library made) is told by its type where that says, and by its shape
+  // where it does not.
+  /** `value`, a new array, written down as one. */
+  array(value) {
+    const marked = call(this.helper("array"), [value]);
+    this.marked.add(marked);
+    return marked;
+  }
+  /** The calls `array` made: each answers the one table it was given. */
+  marked = /* @__PURE__ */ new WeakSet();
+  /** Luau reaching the record of arrays: the bundle's, or this file's own. */
+  arrays() {
+    return this.options.module?.arrays ?? this.helper("arrays").name;
+  }
+  typeofExpression(node) {
+    const known = this.options.types?.typeofTables.get(node);
+    let argument = node.argument;
+    while (argument.type === "ParenthesizedExpression") argument = argument.expression;
+    const value = this.expression(argument);
+    return call(this.helper("typeof"), known ? [value, string(known)] : [this.keptToOne(value)]);
+  }
   /** The local a library's runtime table gets in this file, emitting it the
    *  first time something asks. Keyed by library and by the key the library
    *  itself chose, so two libraries' tables never collide. */
@@ -487,6 +488,46 @@ var Lowerer = class {
   }
   helperDefinitions() {
     const out = [];
+    const runtimes = this.runtimeDefinitions();
+    if (this.helpers.has("concat")) this.helper("array");
+    const marker = this.helpers.get("array");
+    const typeOf = this.helpers.get("typeof");
+    if (marker || typeOf) {
+      const arrays = this.arrays();
+      const own = this.helpers.get("arrays");
+      if (own) {
+        out.push(...parseLuau(`local ${own} = ${this.builtin("setmetatable").name}({}, { __mode = "k" })`).body.statements);
+      }
+      if (marker) {
+        out.push(...parseLuau(`
+local function ${marker}(t)
+	${arrays}[t] = true
+	return t
+end`).body.statements);
+      }
+      if (typeOf) {
+        out.push(...parseLuau(`
+local function ${typeOf}(value, known)
+	local name = ${this.builtin(this.lua51 ? "type" : "typeof").name}(value)
+	if name ~= "table" then
+		return name
+	end
+	if known ~= nil then
+		return known
+	end
+	if ${arrays}[value] then
+		return "array"
+	end
+	if ${this.builtin("getmetatable").name}(value) ~= nil then
+		return "object"
+	end
+	if #value > 0 then
+		return "array"
+	end
+	return "object"
+end`).body.statements);
+      }
+    }
     const assign2 = this.helpers.get("assign");
     if (assign2) {
       out.push(localFunction(assign2, functionBody(["target"], [
@@ -501,25 +542,11 @@ var Lowerer = class {
         returns([identifier("target")])
       ], true)));
     }
-    for (const { index: index2, runtime: runtime2, name } of this.loweringUsed) {
-      const { plugin: plugin2, from } = this.lowerings[index2];
-      const source = plugin2.runtime?.[runtime2];
-      if (source === void 0) {
-        this.diagnostics.push({
-          message: `'${from}' asked for a runtime it does not have: '${runtime2}'`,
-          line: 1,
-          column: 1
-        });
-        continue;
-      }
-      const lines = this.options.module?.lines ?? "nil";
-      const fail = this.options.module?.fail ?? "nil";
-      out.push(...parseLuau(source.replace(/__NAME__/g, name).replace(/__LINES__/g, lines).replace(/__FAIL__/g, fail)).body.statements);
-    }
+    out.push(...runtimes);
     const concat = this.helpers.get("concat");
     if (concat) {
       out.push(localFunction(concat, functionBody([], [
-        local(["result"], [table([])]),
+        local(["result"], [this.array(table([]))]),
         numericFor("i", number(1), selectCount(this.builtin("select")), [
           local(["part"], [call(this.builtin("select"), [identifier("i"), vararg()])]),
           callStatement(call(member(this.builtin("table"), "move"), [
@@ -535,6 +562,26 @@ var Lowerer = class {
     }
     return out;
   }
+  /** The runtime tables the file's libraries were asked for. */
+  runtimeDefinitions() {
+    const out = [];
+    for (const { index: index2, runtime: runtime2, name } of this.loweringUsed) {
+      const { plugin: plugin2, from } = this.lowerings[index2];
+      const source = plugin2.runtime?.[runtime2];
+      if (source === void 0) {
+        this.diagnostics.push({
+          message: `'${from}' asked for a runtime it does not have: '${runtime2}'`,
+          line: 1,
+          column: 1
+        });
+        continue;
+      }
+      const lines = this.options.module?.lines ?? "nil";
+      const fail = this.options.module?.fail ?? "nil";
+      out.push(...parseLuau(source.replace(/__NAME__/g, name).replace(/__LINES__/g, lines).replace(/__FAIL__/g, fail).replace(/__ARRAY__/g, () => this.helper("array").name)).body.statements);
+    }
+    return out;
+  }
   // --------------------------------------------------------
   // Modules
   // --------------------------------------------------------
@@ -1287,7 +1334,7 @@ end
           number(pattern.elements.length + 1),
           unary("#", source),
           number(1),
-          table([])
+          this.array(table([]))
         ]);
         const rest = this.restTarget(pattern.rest, elements, mode, after);
         after.push(...rest.then);
@@ -1341,7 +1388,7 @@ end
     const names = [];
     for (const p of params) {
       if (p.rest) {
-        prelude.push(local([this.name(p.name)], [table([{ type: "TableFieldPositional", value: vararg() }])]));
+        prelude.push(local([this.name(p.name)], [this.array(table([{ type: "TableFieldPositional", value: vararg() }]))]));
         continue;
       }
       const name = p.pattern ? this.names.fresh("arg") : this.name(p.name);
@@ -1399,6 +1446,7 @@ end
         return binary(node.operator, left, right);
       }
       case "UnaryExpression":
+        if (node.operator === "typeof") return this.typeofExpression(node);
         return unary(node.operator, this.expression(node.argument));
       case "SuperExpression":
         return this.superClassReference(node);
@@ -1439,6 +1487,9 @@ end
   callValues(node) {
     const chain = optionalChain(node);
     if (chain) return this.optionalChainExpression(chain);
+    if (node.type === "CallExpression" && (node.callee.type === "SuperExpression" || node.callee.type === "MemberExpression" && node.callee.object.type === "SuperExpression")) {
+      return this.expression(node);
+    }
     const object2 = linkObject(node);
     if (node.type === "CallExpression" && object2.type === "Identifier") {
       return this.link(node, this.reference(object2));
@@ -1450,7 +1501,7 @@ end
    *  kept to one there, `f((g()))`. Every value is taken only where the
    *  program asks for them, as an array's last element: `[g()]`. */
   keptToOne(value) {
-    return expandsToMany(value) ? parenthesized(value) : value;
+    return expandsToMany(value) && !this.marked.has(value) ? parenthesized(value) : value;
   }
   /** Is this `scriptArgs` the language's own, not a name the file declared? */
   isLanguageGlobal(node) {
@@ -1731,7 +1782,7 @@ end
   arrayExpression(node) {
     const elements = packs(node.elements).items;
     if (!elements.some((e) => e.type === "SpreadElement")) {
-      return table(elements.map((e) => ({ type: "TableFieldPositional", value: this.expression(e) })));
+      return this.array(table(elements.map((e) => ({ type: "TableFieldPositional", value: this.expression(e) }))));
     }
     const parts = [];
     let current = [];
@@ -2021,11 +2072,13 @@ import {
   applyDirectives,
   UNUSED_EXPECT_ERROR,
   ParseError,
-  LexError
+  LexError,
+  luauString as luauString3
 } from "@tilua/parser";
 import { parse as parseLuau2, parseExpressionFromSource as parseExpressionFromSource2, print } from "luau-parser";
 
 // src/linemap.ts
+import { luauString as luauString2 } from "@tilua/parser";
 function statementsOf(node) {
   const out = [];
   const visit = (value) => {
@@ -2058,7 +2111,7 @@ function buildLineMap(emitted, printed, origins) {
 }
 function lineMapSource(map) {
   const entries = [...map.entries()].sort((a, b) => a[0] - b[0]);
-  const quoted = (s) => JSON.stringify(s.replace(/\\/g, "/"));
+  const quoted = (s) => luauString2(s.replace(/\\/g, "/"));
   return `{${entries.map(([line, o]) => `[${line}]={${quoted(o.file)},${o.line}}`).join(",")}}`;
 }
 
@@ -2119,6 +2172,7 @@ async function bundle(options) {
         require: requireExpression,
         lines: `${G}.lines`,
         fail: `${G}.fail`,
+        arrays: `${G}.arrays`,
         resolve: (specifier) => {
           const target = resolveModulePath(file, specifier, config);
           if (!target || target.endsWith(".d.tilua") || !sources.has(target)) return void 0;
@@ -2164,6 +2218,7 @@ async function bundle(options) {
   const assignment = program2.body.statements[1];
   if ([...modules.values()].some((m) => m.usesScriptArgs)) {
     program2.body.statements.unshift(local(["scriptArgs"], [table([{ type: "TableFieldPositional", value: { type: "VarargExpression" } }])]));
+    program2.body.statements.push(...parseLuau2(`${G}.arrays[scriptArgs] = true`).body.statements);
   }
   const modulesTable = assignment.type === "AssignmentStatement" && assignment.values[0].type === "TableExpression" ? assignment.values[0].fields.find((f) => f.type === "TableFieldNamed" && f.name.name === "modules")?.value : void 0;
   if (!modulesTable) throw new Error("@tilua/compiler: the bundle runtime has no modules table");
@@ -2185,7 +2240,7 @@ async function bundle(options) {
   const result = names.fresh("result");
   const entryStatements = parseLuau2(`
 local ${ok}, ${result} = xpcall(function()
-    return ${G}.require(${JSON.stringify(sources.get(entry).name)})
+    return ${G}.require(${luauString3(sources.get(entry).name)})
 end, ${G}.fail)
 if not ${ok} then
     error(${result}, 0)
@@ -2207,6 +2262,9 @@ function runtime(G) {
 local ${G}
 ${G} = {
     modules = {},
+    -- Every array the program made, so \`typeof\` can tell one from an object.
+    -- The keys are held weakly: being written down keeps no array alive.
+    arrays = setmetatable({}, { __mode = "k" }),
     -- Filled in just before the entry runs: bundle line -> { file, line }.
     lines = nil,
     -- What an error nothing caught says, in the project's files: the bundle's
@@ -2214,19 +2272,64 @@ ${G} = {
     -- and a traceback of those places follows. A message that is not a string
     -- is left as it is, and a position that is not this bundle's (a library
     -- that raised its error with one already mapped) is left alone.
+    --
+    -- It is an \`xpcall\` handler, and a handler that fails loses the error
+    -- altogether: Luau reports only "error in error handling". So the work is
+    -- done under \`pcall\`, leaning on nothing it has not checked is there (an
+    -- executor may lack \`debug.info\`, or refuse it), and an error it cannot
+    -- map is still answered as Luau raised it, with why.
     fail = function(message)
+        -- Taken first, before anything that can fail. Level 3 is the frame
+        -- that raised: past \`pcall\` and this handler.
+        local trace
+        if debug ~= nil and debug.traceback ~= nil then
+            local ok, text = pcall(debug.traceback, "", 3)
+            if ok and type(text) == "string" then
+                trace = text
+            end
+        end
+        local ok, described = pcall(${G}.describe, message, trace)
+        if ok then
+            return described
+        end
+        if type(message) ~= "string" then
+            return message
+        end
+        local why = type(described) == "string" and described or "unknown"
+        return message .. "\\n(tilua could not map this error to the project's files: " .. why .. ")" .. (trace or "")
+    end,
+    -- \`fail\`'s work. \`trace\` is a traceback from where the error was
+    -- raised, or nil when none could be taken.
+    describe = function(message, trace)
         if type(message) ~= "string" then
             return message
         end
         local lines = ${G}.lines
         if lines == nil then
-            return debug.traceback(message, 2)
+            return message .. (trace or "")
         end
+        -- The bundle's name, as a position in a message spells it: where this
+        -- function is, asked of the debug library by the function rather
+        -- than by a level, which \`pcall\` would shift. Failing that, a message
+        -- starts with the position it was raised at.
         local chunk
-        if debug.info ~= nil then
-            chunk = debug.info(1, "s")
-        else
-            chunk = debug.getinfo(1, "S").short_src
+        if debug ~= nil and debug.info ~= nil then
+            local found, source = pcall(debug.info, ${G}.describe, "s")
+            if found and type(source) == "string" then
+                chunk = source
+            end
+        end
+        if chunk == nil and debug ~= nil and debug.getinfo ~= nil then
+            local found, info = pcall(debug.getinfo, ${G}.describe, "S")
+            if found and type(info) == "table" and type(info.short_src) == "string" then
+                chunk = info.short_src
+            end
+        end
+        if chunk == nil then
+            chunk = message:match("^(.-):%d+:")
+        end
+        if chunk == nil then
+            return message .. (trace or "")
         end
         local prefix = chunk:gsub("%p", "%%%0")
         local function place(line)
@@ -2240,7 +2343,7 @@ ${G} = {
             return place(line)
         end)
         local frames = {}
-        for frame in debug.traceback("", 2):gmatch("[^\\n]+") do
+        for frame in (trace or ""):gmatch("[^\\n]+") do
             local line = frame:match(prefix .. ":(%d+)")
             local at = line ~= nil and place(line) or nil
             if at ~= nil then