luaut-parser 3.1.0 → 5.0.0

package/README.md

@@ -48,11 +48,11 @@ be, so a tool never has to re-derive a type from text.
 use it for editors, where the text is usually mid-edit. An error costs as
 little of the tree as it can: a broken value becomes an `ErrorExpression`
 (typed `any`) in its place, a broken field or argument is skipped to the next
-`,`, a missing comma between fields on separate lines, or a missing `)`, `}`,
-`then`, `do` or `end`, is recorded and read past — a missing `end` is placed
-by indentation — and an unclosed string ends at its line. Skipping never lets
-an `end` or `}` inside a skipped function or object close the block around
-it. Valid code parses to exactly the same tree as `parse`.
+`,`, a missing comma between fields on separate lines, or a missing `)` or
+`}`, is recorded and read past — a missing `}` is placed by indentation — and
+an unclosed string ends at its line. Skipping never lets a `}` inside a
+skipped function or object close the block around it. Valid code parses to
+exactly the same tree as `parse`.
 
 Neither analysis mutates the AST; both return side tables.
 
@@ -117,9 +117,79 @@ restating them.
 TypeScript syntax and semantics wherever they fit, Lua semantics where they
 must.
 
+**Blocks** — braces, and a condition in parentheses:
+
+```luau
+if (n < 0) {
+    return "negative"
+} elseif (n == 0) {
+    return "zero"
+} else {
+    return "positive"
+}
+
+while (going) { step() }
+for (i = 1, 10) { total += i }
+for (name, value in pairs(t)) { print(name, value) }
+repeat { step() } until (done)
+do { ... }
+
+function greet(name: string): string {
+    return `hello ${name}`
+}
+
+class Dog extends Animal {
+    function speak(): string { return "woof" }
+}
+```
+
+The parentheses are not decoration: `f {}` is a call with a table argument, so
+without them `if ready { ... }` would be a call of `ready` followed by a block.
+
+There is no `end` in luaut, and `then` is not a word it knows.
+
+`and`, `or` and `not` stay words; `{}` is still an object literal everywhere a
+value is expected, and `[]` an array.
+
+**Arrows** — one for both, as TypeScript writes them. `(a: number) => string`
+is a function type; `(a: number) => a` is a function. Which one a `=>` makes is
+decided by where it stands, since a type and a value never share a place.
+
+```luau
+type Reducer = (total: number, value: number) => number
+
+const double = (x: number) => x * 2
+const add: Reducer = (a, b) => a + b        -- parameters typed by the contract
+const shown = (n: number): string => tostring(n)
+const identity = <T>(v: T) => v
+
+each(n => print(n))                          -- one parameter needs no parens
+
+const logged = (n: number) => {              -- a block body is a block,
+    print(n)                                 -- as in TypeScript,
+    return n
+}
+const wrap = (n: number) => ({ value: n })   -- so an object is parenthesized
+```
+
+An arrow is a function expression written short — there is no second kind of
+function — so `this` inside one is the `this` of the method around it, which
+is what a JavaScript arrow is for.
+
+**Moving a file over** — `end`, `then`, `do` as a block opener, and `->` for a
+function type are Lua's spellings, and luaut no longer reads any of them.
+`npx tsx scripts/to-braces.ts <file|dir>` rewrites a file written in them,
+and `scripts/to-braces-sources.ts <file>` does the same for luaut written
+inside a TypeScript file, which is where a test suite keeps most of it. Each
+rewrite is parsed and compared with the tree the original made before it is
+written; a file it cannot say the same thing about is left alone.
+
+Both scripts need a parser that still reads the old spellings, so run them
+from a checkout of the commit before they were dropped.
+
 **Declarations** — `const` and `let` only; Lua's `local` is gone.
 
-**Functions** — `function name() ... end` declares `name` in the enclosing
+**Functions** — `function name() { ... }` declares `name` in the enclosing
 scope; like a TypeScript function declaration it cannot be reassigned.
 `const` and `let` do not apply to functions. `function T.name()` and
 `function T:name()` define a member.
@@ -127,7 +197,7 @@ scope; like a TypeScript function declaration it cannot be reassigned.
 **Hoisting** — a function declaration is visible to its whole block, above
 itself too, so `let r: ReturnType<typeof load>` may come before `function
 load()`. A closure reads the name its own value is bound to, as in JavaScript
-(`let m = { clear: function() m.items = {} end }`), and a later name in the
+(`let m = { clear: function() { m.items = {} } }`), and a later name in the
 same block; the compiler declares such a name before the statement that fills
 it. A module's top-level names are visible to code that runs later —
 function bodies and `typeof` — wherever that code is written, since a bundle
@@ -160,6 +230,63 @@ brings in names that are types and nothing else: unlike TypeScript, using one
 as a value is an error, and only type positions — `typeof A` included — may
 name it. Compiled code keeps no trace of it.
 
+**Array and string methods** — an array and a string answer to methods
+written with `:`, the way JavaScript writes them:
+
+```luau
+const long = names:filter(n => #n > 3):map(string.upper)
+const first = names:find(n => n:startsWith("A"))
+print(names:join(", "), text:trim(), text:replaceAll(",", ";"))
+```
+
+Which methods those are is not the language's business. The analyzer looks for
+two types by name — `ArrayMethods<T>` and `StringMethods` — and reads an
+array's or a string's members out of whichever type library declared them;
+without such a library an array has no methods at all.
+
+Running them is that library's business too. A library points at a JavaScript
+module in its package.json, and the compiler asks it what a call becomes:
+
+```json
+"luaut": { "types": "index.d.luaut", "lowering": "lowering.mjs" }
+```
+
+```js
+// @ts-check
+/** @type {import("luaut-parser").LoweringPlugin} */   // the contract, declared here
+const plugin = {
+    runtime: { array: "local __NAME__ = {}\nfunction __NAME__.filter(t, test) ... end" },
+    methodCall({ method, receiver, use }) {
+        if (receiver?.kind === "array" && method === "filter") {
+            return { callee: `${use("array")}.filter` }
+        }
+        return undefined
+    },
+}
+export default plugin
+```
+
+`receiver` is the luaut type the analyzer worked out, `use(key)` gives the
+local name that table got — emitted once, at the top of the output, only if a
+call needed it — and the receiver is passed as the call's first argument. An
+answer of `undefined` leaves an ordinary Luau method call, which is what
+`text:upper()` wants, since a string already answers to it.
+
+The compiler lowers the language and nothing else: `filter` appears nowhere in
+it.
+
+`@luaut/lua` ships the JavaScript-shaped set; there, indices are Luau's (the
+first element is 1, `indexOf` answers `nil` rather than -1) and `push`, `pop`,
+`shift`, `unshift`, `sort` and `reverse` change the array they are called on.
+
+**A `(` that starts a line** continues the statement above it, as in Lua and
+in JavaScript — `const v = map[key]` followed by `("A"):upper()` is one
+statement, a call of `map[key]`. luaut says so rather than letting it pass:
+write `;` before the `(` when a new statement was meant.
+
+**Object types** — `{ name: T, name?: T, [K]: V }`, and a name that is not an
+identifier is quoted, as in the literal: `{ "Respawn After Kill": boolean }`.
+
 **Optionality** — there is no `T?` shorthand. `?` in type position always
 belongs to a conditional type, and in expression position to a ternary or an
 optional chain.
@@ -177,7 +304,7 @@ nothing further along the chain runs, arguments included: `folder?:FindFirstChil
 is a `string | nil`. The `?` must touch the `.` or `:`; `c ? a : b` stays a
 ternary. Parentheses end a chain. A chain cannot be assigned to (`a?.b = 1` is
 an error). A chain that got through narrows what it tested: inside
-`if part?.Parent then`, and `if part?.Name == "Door" then`, `part` is not nil.
+`if (part?.Parent)`, and `if (part?.Name == "Door")`, `part` is not nil.
 
 **Classes** — types are structural, except for classes. A definitions file
 declares one with `declare class`, and it is nominal, as Roblox's classes are:
@@ -194,12 +321,210 @@ has (`{ Name: string }`). It is not a table, though, so `typeof(part)` picks
 the `"Instance"` overload, not `"table"`. Members are inherited, and a subclass
 may narrow one (`Parent: SomeFolder`).
 
+**`class ... { }`** — a class written in code, rather than declared in a
+definitions file. It is sugar over the Lua idiom, and the shape it stands for
+is exactly that one: the class is a single table holding the methods and the
+statics, and an instance is a table whose metatable points at it. An instance
+therefore reaches *the class* — nothing is copied per instance, and there is
+no prototype chain of an instance's own.
+
+```luau
+class Animal {
+    name: string                -- set by the constructor
+    legs = 4                    -- set on every instance, before the body runs
+    static count = 0            -- on the class table, once
+
+    constructor(name: string) {
+        this.name = name
+        Animal.count += 1
+    }
+
+    function speak(): string {
+        return `${this.name} makes a sound`
+    }
+
+    get label(): string {       -- read as a property, run as a function
+        return `<${this.name}>`
+    }
+
+    set label(value: string) {
+        this.name = value
+    }
+
+    static function made(): number {
+        return Animal.count
+    }
+}
+
+class Dog extends Animal {
+    breed: string
+
+    constructor(name: string, breed: string) {
+        super(name)             -- required: it is what fills in the base
+        this.breed = breed
+    }
+
+    function speak(): string {
+        return `${super.speak()} (woof)`
+    }
+}
+
+const rex = new Dog("Rex", "shiba")
+rex:speak()                     -- the receiver is `this`
+rex.label = "Max"               -- the setter
+Dog.made()                      -- a static, inherited from Animal
+```
+
+The receiver is written `this`, and it is an ordinary first parameter: a
+method's type is `(this: Dog, ...) => R`, so `rex:speak()` supplies it the way
+`function T:m()` supplies `self`. `new Dog(x)` *is* `Dog.new(x)` — the same
+function, callable by hand and passable as a value.
+
+A declaration names two things. As a **type**, `Dog` is the type of its
+instances, nominal the same way a `declare class` is: a table with the same
+members is not one, and only `Dog` and what extends it are assignable to it.
+As a **value**, `Dog` is the class table — its statics, and the `new` that
+builds an instance. `export class` exports both.
+
+Two links are always there, and they are what the memory model promises:
+
+```luau
+rex.ClassObject == Dog          -- an instance names its class
+Dog.ParentClass == Animal       -- a class names the one it extends
+Animal.ParentClass == nil       -- and a root class extends nothing
+```
+
+Both live on the class table, so an instance carries neither.
+
+**Generic classes** — `class Box<T> { ... }`. The name is then a generic type,
+and `Box<number>` and `Box<string>` are both `Box` but neither is the other:
+
+```luau
+class Box<T> {
+    value: T
+    constructor(value: T) {
+        this.value = value
+    }
+    function get(): T {
+        return this.value
+    }
+    function map<R>(f: (value: T) => R): Box<R> {
+        return new Box(f(this.value))
+    }
+}
+
+const n = new Box(1)               -- Box<number>, read off the argument
+const s = new Box<string>("a")     -- or written out
+const held: number = n:get()
+
+class Ints extends Box<number> {   -- extending one fixes its argument
+    constructor(n: number) { super(n) }
+}
+```
+
+A function takes the argument off what it is handed: `function unwrap<T>(b:
+Box<T>): T` given a `Box<boolean>` returns `boolean`.
+
+**A class as a value** — `const Counter = class { ... }`, and `export default
+class { ... }`. It may be named, and then the name is visible only inside its
+own body, as in JavaScript; an anonymous one is known by whatever holds it.
+Two of them are different types however alike they look. A class written as a
+value takes no type parameters — nothing could write the arguments.
+
+`export default class Name { ... }` declares `Name` here as well as exporting
+it, as TypeScript's does, and importing it brings in the type too:
+
+```luau
+import Box from "./box"            -- `Box` is the class *and* the type
+const held: Box<number> = new Box(1)
+```
+
+Reported: a field with a type that nothing gives a value (`name: string` that
+the constructor never assigns), a derived constructor that does not call
+`super(...)`, `extends` naming something that is not a class, a chain that
+closes on itself, a member written twice, and a member named one of the words
+the compiler builds the class table out of (`new`, `ClassObject`,
+`ParentClass`, `__init`, `__index`, `__newindex`, `__getters`, `__setters`,
+`__dynamic`).
+
+**Varargs** — `...` is Lua's pack, and every name on the left reads one of
+it: with `...: number`, `const a, b = ...` gives two numbers. `[...]` puts the
+whole pack in an array.
+
+**Rest parameters** — `...name: T[]` is JavaScript's: every argument from that
+position on, as an array. It is last, and the call signature is the same one
+`...: T` describes — the difference is only what the body sees.
+
+```luau
+function join(separator: string, ...parts: string[]): string {
+    return table.concat(parts, separator)   -- `parts` is a string[] here
+}
+
+join("-", "a", "b")       -- and a vararg call out here
+join("-", 1)              -- Argument of type '1' is not assignable to 'string'
+
+function firstOf<T>(...items: T[]): T | nil {
+    return items[1]
+}
+
+firstOf(1, 2)             -- number | nil: the arguments say what `T` is
+```
+
+A type is written the same way: `type Reporter = (level: string, ...lines:
+string[]) => ()` describes the same calls as `(level: string, ...string) =>
+()`. Without an annotation a rest parameter is `unknown[]`; annotated with
+something that is not an array, it is reported.
+
+**Spreads** — `...xs` puts what an array holds into any list of values, as
+JavaScript does: a call's arguments, a `return`, a declaration, an assignment.
+Bare `...` is unchanged, and is still the pack.
+
+```luau
+join("-", ...names)              -- every name
+join("-", ...names, "z")         -- and one more after them
+add3(...nums)                    -- however many `nums` turns out to hold
+
+function three(): (number, number, number) {
+    return ...nums
+}
+
+const first, second = ...names   -- one each, as far as the names go
+```
+
+What the array holds is checked against what it fills. How many it holds is
+not known, so nothing is said about the count — unless it is a tuple, which
+holds a known value at each position and is checked one by one. Spreading
+something that is not a list is reported.
+
+**Branded types** — nothing in the type model is about branding; an
+intersection already means it. `string & { __brand }` is assignable to
+`string`, and `string` is not assignable to it, which is the whole of it:
+
+```luau
+type UserId = string & { readonly __brand: "UserId" }
+type PostId = string & { readonly __brand: "PostId" }
+
+declare function findUser(id: UserId): string
+
+const id = "raw" as UserId      -- `as` is how one is made
+findUser(id)                    -- ok
+findUser("raw")                 -- '"raw"' is not assignable to 'UserId'
+findUser(postId)                -- 'PostId' is not assignable to 'UserId'
+
+#id                             -- still a string: 5
+id:upper()                      -- and its methods, giving a plain string
+```
+
+Anything that builds a new value builds an unbranded one — which is the point:
+the brand says where the value came from. It works on any type (`number & {
+__brand }`), and survives being stored, indexed and narrowed.
+
 **Callbacks** — a function written where a function type is expected takes
-its parameter types from it: in `signal:Connect(function(player) ... end)`,
+its parameter types from it: in `signal:Connect(player => ... )`,
 `player` is typed from `Connect`. The same applies to an annotated `const`
-and to an assignment such as `remote.OnServerInvoke = function(player) ...`.
+and to an assignment such as `remote.OnServerInvoke = function(player) { ... }`.
 
-**Type packs** — `type Signal<T... = ...any> = { Connect: (self, cb: (T...) -> ()) -> () }`.
+**Type packs** — `type Signal<T... = ...any> = { Connect: (self, cb: (T...) => ()) => () }`.
 A pack parameter takes every type argument from its position on:
 `Signal<Player, string>`, `Signal<()>` for none.
 
@@ -235,7 +560,7 @@ already get.
 
 **Narrowing** follows TypeScript's model: references (`x`, `x.a.b`, `x["k"]`)
 rather than just variables, discriminated unions at any depth, `and`/`or`,
-early return, `break`/`continue`, `error()` (declared `-> never`), user type
+early return, `break`/`continue`, `error()` (declared `=> never`), user type
 guards (`v is T`), and assertion signatures (`asserts v`).
 
 Reading a member of, indexing or calling a value that may be nil is an error
@@ -276,8 +601,8 @@ as in TypeScript 4.9:
 type Shape = { kind: "circle" | "rect", size: number }
 const circle = { kind: "circle", size: 2 } satisfies Shape  -- { kind: "circle", size: number }
 const handlers = {
-    Click: function(x) return x + 1 end,                     -- x: number, from the contract
-} satisfies { [string]: (x: number) -> number }
+    Click: x => x + 1,                                       -- x: number, from the contract
+} satisfies { [string]: (x: number) => number }
 ```
 
 The contract types callbacks and empty arrays, and a literal stays a literal