@tilua/compiler 1.0.2 → 2.0.0

package/README.md

@@ -65,10 +65,14 @@ JavaScript module the build loads.
 | `function f(n = 1, { x })` | `function f(n, arg) if n == nil then n = 1 end local x = arg.x ...` |
 | `const` / `let` | `local` |
 | `class C { … }` | one table for the class, one per instance — see below |
-| `new C(x)` | `C.new(x)` |
-| `[...]` | `{...}` — the varargs as an array |
+| `return [a, b]` | `return { a, b }` — several results are an array |
+| `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]` |
+| `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 = {...}` |
-| `f(a, ...xs)` / `return ...xs` | `table.unpack(xs)` in the last position |
+| `scriptArgs` | the chunk's own `...`, as `local scriptArgs = { ... }` |
+| `f(a, ...xs)` | `table.unpack(xs)` in the last position |
 | `f(...xs, a)` | the list built first, then `table.unpack` of it |
 | `x as T`, `x satisfies T`, types, `declare` | removed |
 | `names:filter(f)` | whatever the type library that declared `filter` says — see below |
@@ -113,8 +117,16 @@ tilua_accessors(Dog)
 
 `__init` is what `super(...)` calls: it runs the constructor on an instance
 that already exists, so a derived class builds one table, not one per level.
-`new` is a real function on the class table — `new Dog(x)` and `Dog.new(x)`
-are the same call.
+`new` is a real function on the class table, and `Dog.new(x)` is how an
+instance is built — the way Luau builds one. An `abstract class` has no `new`,
+and an `abstract` method no function: both exist only to be checked.
+
+A method named for a metamethod — `__add`, `__tostring`, `__call`, … — is an
+ordinary function on the class table, and since the class table is its
+instances' metatable, it works as one. Luau reads metamethods off the
+metatable with `rawget`, never through its `__index`, so a class would not
+inherit its base's: `tilua_class` copies them into each class that extends
+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
@@ -168,6 +180,33 @@ needed it; the receiver becomes the call's first argument unless
 `passReceiver: false`. The last library loaded is asked first, and `undefined`
 leaves an ordinary Luau method call.
 
+Hooks also get the call site (`at`) and what the compiler knew about each
+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.
+`console:log` is not built into the compiler: `@tilua-types/lua` implements it
+with these hooks.
+
+## Errors at runtime
+
+A bundle is one Luau file, so a position Luau reports names a line of that
+file. The entry therefore runs under `xpcall`. If an error reaches the top,
+its message is rewritten from bundle lines to the places in the project that
+wrote them, a traceback of those places is added, and the error is raised
+again:
+
+```
+src/util.tilua:3: attempt to index nil with 'value'
+    at src/util.tilua:3 (boom)
+    at src/main.tilua:3 (load)
+```
+
+A message that is not a string is raised unchanged. A position that is already
+in the project's files, such as one from `error` in `@tilua-types/lua`, is
+left as it is.
+
 ## Modules
 
 Roblox's `require` takes an Instance, so the bundle has its own. Each module