Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.43.0

0.43.0 / src / front / parser.lucb

#==============================================================================================
#
#   parser - Recursive descent over the token buffer
#
#   DESCRIPTION:
#       The grammar of base.md §21, one function per production, with the expression
#       precedence ladder of §7.10. A `(T)x` cast is recognised only when the parenthesised
#       text is cast-shaped (§7.5), and a `[` after a name holds type arguments only when it
#       is followed by `(` or `.`. The first syntax error stops the parse and carries its line
#       and column.
#
#==============================================================================================

import front.ast
import front.lexer
import front.source
import front.token
import memory
import support.list as lists
import strings
## A syntax error.
pub let syntax: ErrorCode = ErrorCode.package(7)
## The source nests or chains deeper than the parser allows.
pub let too_deep: ErrorCode = ErrorCode.package(8)

let max_nest: u32 = 100
## A chain of calls or operators, one level per link, may be longer than nesting is deep.
let max_chain: u32 = 300

## The recursive-descent parser over a source's tokens.
pub struct Parser:
    var src: source.Source
    var tokens: token.Token[]
    var count: usize
    var pos: usize
    var scratch: u8[]
    var nest: u32
    ## The standard modules declare the core names they define (§3.5).
    pub var allow_core_names: bool
    ## The type whose body or extension is being read, whose `linked` methods name their
    ## receiver (§9.8); empty outside one.
    var member_of: str = ""

    ## Lex the whole source into the current allocator.
    pub static func over(src: source.Source, scratch: u8[]) -> Parser!:
        var lx = lexer.Lexer.over(src)
        # about a token every four bytes, so most sources never grow the list
        var tokens = try lists.List[token.Token].create(src.bytes.length // 4 + 16)
        while true:
            # a lexing error is reported where the lexer stopped
            let t = lx.next() catch failure:
                let (line, column) = lx.error_position()
                let half = scratch.length // 2
                let (file, mapped_line, mapped_column) = lx.src.fragment_of(line, column)
                let message = try strings.format(scratch[..<half], f"{file}:{mapped_line}:{mapped_column}: {failure.message}")
                error(failure.code, message)
            try tokens.push(t)
            if t.kind == token.Kind.eof:
                break
        return Parser(src = src, tokens = tokens.items, count = tokens.count, pos = 0, scratch = scratch, nest = 0)

    # -- the token cursor ------------------------------------------------------------------

    func cur() -> token.Token:
        return self.tokens[self.pos]

    func peek(ahead: usize) -> token.Token:
        let i = self.pos + ahead
        if i >= self.count:
            return self.tokens[self.count - 1]
        return self.tokens[i]

    ## Every token of the source, for the formatter's comment search.
    pub func token_span() -> const token.Token[]:
        return self.tokens[..<self.count]

    ## The source text token `t` spans.
    pub func text_of(t: token.Token) -> str:
        return self.src.text(t.start, t.end)

    ## Whether the current token is of `kind`.
    pub func at(kind: token.Kind) -> bool:
        return self.cur().kind == kind

    ## Whether the current token is the operator `spelling`.
    pub func at_op(spelling: str) -> bool:
        let t = self.cur()
        return t.kind == token.Kind.operator and self.text_of(t) == spelling

    ## Whether the current token is the keyword `word`.
    pub func at_kw(word: str) -> bool:
        let t = self.cur()
        return t.kind == token.Kind.keyword and self.text_of(t) == word

    func at_name(word: str) -> bool:
        let t = self.cur()
        return t.kind == token.Kind.name and self.text_of(t) == word

    func peek_op(ahead: usize, spelling: str) -> bool:
        let t = self.peek(ahead)
        return t.kind == token.Kind.operator and self.text_of(t) == spelling

    ## Whether the operand just parsed ended with a suite (a `match` expression's arms):
    ## the expression ends with it, and what follows on the next line is a statement, not
    ## an operator, a conditional, an `else` or a `catch` of it (§7.8).
    func ended_suite() -> bool:
        return self.pos > 0 and self.tokens[self.pos - 1].kind == token.Kind.dedent

    ## The current token, advancing past it.
    pub func take() -> token.Token:
        let t = self.cur()
        if self.pos + 1 < self.count:
            self.pos += 1
        return t

    ## Consume the current token if it is the operator `spelling`; whether it was.
    pub func eat_op(spelling: str) -> bool:
        if self.at_op(spelling):
            _ = self.take()
            return true
        return false

    func eat_kw(word: str) -> bool:
        if self.at_kw(word):
            _ = self.take()
            return true
        return false

    ## The message lives in the first half of `scratch`; `what` may live in the second.
    pub func fail(what: str) -> ast.Node*!:
        let t = self.cur()
        let half = self.scratch.length // 2
        let (file, line, column) = self.src.fragment_of(t.line, t.column)
        let message = try strings.format(self.scratch[..<half], f"{file}:{line}:{column}: {what}")
        error(syntax, message)

    func spelled(prefix: str, spelling: str) -> str!:
        let half = self.scratch.length // 2
        return try strings.format(self.scratch[half..], f"{prefix}`{spelling}`")

    func expect_op(spelling: str) -> !:
        if not self.eat_op(spelling):
            _ = try self.fail(try self.spelled("expected ", spelling))

    func expect_kw(word: str) -> !:
        if not self.eat_kw(word):
            _ = try self.fail(try self.spelled("expected ", word))

    func expect_newline() -> !:
        if self.at(token.Kind.newline):
            _ = self.take()
            return
        if self.at(token.Kind.eof) or self.at(token.Kind.dedent):
            return
        # a `catch` suite or a same-line suite has already consumed the line end
        if self.pos > 0:
            let prev = self.tokens[self.pos - 1].kind
            if prev == token.Kind.newline or prev == token.Kind.dedent:
                return
        # `f(x catch failure: recover 0)`: the enclosing bracket ends the suite
        if self.at_op(")") or self.at_op("]") or self.at_op("}"):
            return
        _ = try self.fail("expected the end of the line")

    ## The current token as a name, or a syntax error.
    pub func expect_name() -> str!:
        if not self.at(token.Kind.name):
            _ = try self.fail("expected a name")
        let word = self.text_of(self.take())
        if token.is_core_name(word) and not self.allow_core_names:
            _ = try self.fail("this name belongs to the language; a declaration cannot take it (§3.5)")
        return word

    ## A member's name, a field's, a method's, an interface requirement's, an enum case's,
    ## or an extern parameter's. None binds a name in any scope (a member is reached through
    ## its value or its type, an extern parameter has no body), so the core names are open
    ## to them: a type's `print` method shadows nothing (§3.5).
    func expect_unscoped_name() -> str!:
        if not self.at(token.Kind.name):
            _ = try self.fail("expected a name")
        return self.text_of(self.take())

    ## `export` before a declaration (§17.6): a word only there, an ordinary name elsewhere.
    func eat_export() -> bool:
        if not self.at_name("export") or self.peek_op(1, ":") or self.peek_op(1, "="):
            return false
        _ = self.take()
        return true

    ## After `.`, a reserved word is an ordinary name; a declaration never takes one.
    func expect_member_name() -> str!:
        if not self.at(token.Kind.name) and not self.at(token.Kind.keyword) and not self.at(token.Kind.integer):
            _ = try self.fail("expected a member name")
        return self.text_of(self.take())

    func at_member_name(ahead: usize) -> bool:
        let k = self.peek(ahead).kind
        return k == token.Kind.name or k == token.Kind.keyword or k == token.Kind.integer

    func skip_newlines():
        while self.at(token.Kind.newline) or self.at(token.Kind.doc_comment):
            _ = self.take()

    func node(kind: ast.Kind, text: str) -> ast.Node*!:
        let t = self.cur()
        return try ast.Node.make(kind, text, t.start, t.line)

    ## A node made of the current token: its text and its position, then consumed.
    func taken(kind: ast.Kind) -> ast.Node*!:
        let t = self.take()
        return try ast.Node.make(kind, self.text_of(t), t.start, t.line)

    ## One level deeper into the tree: a source that nests past `max_nest` (blocks,
    ## brackets, and operators alike, `********x` included) is refused here, where the
    ## recursion is, rather than left to the stack.
    func enter() -> !:
        self.nest += 1
        if self.nest > max_nest:
            _ = try self.fail("the source nests too deeply")

    func leave():
        self.nest -= 1

    # -- module and declarations ----------------------------------------------------------
    pub func parse_module() -> ast.Node*!:
        let module = try self.node(ast.Kind.module, self.src.path)
        var tail: ast.Node*? = none
        self.skip_newlines()
        while not self.at(token.Kind.eof):
            let d = try self.parse_top_decl()
            ast.append(&module.body, &tail, d)
            self.skip_newlines()
        return module

    ## A declaration begins at its first word, `pub` or an attribute included, so a blank
    ## line or a comment before it is found from there.
    func parse_top_decl() -> ast.Node*!:
        let first = self.cur()
        let d = try self.parse_top_decl_words()
        if d.start > first.start:
            d.start = first.start
            d.line = first.line
        return d

    func parse_top_decl_words() -> ast.Node*!:
        if self.at_kw("import") or self.at_kw("from"):
            return try self.parse_import()
        if self.at_kw("test"):
            return try self.parse_test()
        if self.at_name("assert"):
            let n = try self.node(ast.Kind.assert_, "")
            _ = self.take()
            n.body = try self.parse_arguments()
            try self.expect_newline()
            return n
        if self.at_kw("asm") and self.peek(1).kind == token.Kind.name and self.peek_op(2, ":"):
            return try self.parse_asm()
        # `extend` is a word only here, before a type's name and `:` (§9.5)
        if self.at_name("extend") and self.peek(1).kind == token.Kind.name and self.peek_op(2, ":"):
            return try self.parse_extend()
        var flags: u32 = 0
        if self.eat_kw("pub"):
            flags |= ast.flag_pub
        if self.eat_export():
            flags |= ast.flag_export
        if self.at_kw("extern"):
            let d = try self.parse_extern()
            d.flags |= flags
            return d
        if self.at_name("handle") and self.peek(1).kind == token.Kind.name and self.peek_op(2, ":"):
            let d = try self.parse_handle()
            d.flags |= flags
            return d
        return try self.parse_decl(flags)

    ## `extend Name:` and methods beneath: more of a type this module declares (§9.5).
    func parse_extend() -> ast.Node*!:
        let n = try self.node(ast.Kind.extend_, "")
        _ = self.take()
        n.text = try self.expect_name()
        try self.open_block()
        let outer = self.member_of
        self.member_of = n.text
        defer self.member_of = outer
        var tail: ast.Node*? = none
        while self.block_continues():
            let m = try self.parse_member(false)
            if m.kind != ast.Kind.func_:
                return try self.fail_at(m, "an extension adds methods; a field belongs in the type's declaration (§9.5)")
            ast.append(&n.body, &tail, m)
        _ = self.take()
        return n

    ## Every `extend Name:` of `module` joined to the declaration of `Name` in the same module,
    ## its methods after the ones the declaration holds, and gone from the module's list, so
    ## the checker and the backends see one type with all of its methods (§9.5).
    pub func merge_extensions(module: ast.Node*) -> !:
        var previous: ast.Node*? = none
        var cursor = module.body
        while let d = cursor:
            cursor = d.next
            if d.kind != ast.Kind.extend_:
                previous = d
                continue
            let found = extended_type(module, d.text)
            if found == none:
                _ = try self.fail_at(d, try self.spelled("no struct, enum, or union of this module is named ", d.text))
            let target = found else return
            var last = target.body
            while let m = last:
                if m.next == none:
                    break
                last = m.next
            if let end = last:
                end.next = d.body
            else:
                target.body = d.body
            if let p = previous:
                p.next = d.next
            else:
                module.body = d.next

    ## An error at node `n`'s position.
    func fail_at(n: ast.Node*, what: str) -> ast.Node*!:
        let half = self.scratch.length // 2
        let (file, line, column) = self.src.located(n.start)
        let message = try strings.format(self.scratch[..<half], f"{file}:{line}:{column}: {what}")
        error(syntax, message)

    ## `handle Name:` with `destroy function` beneath (§17.7): an opaque pointer-shaped
    ## type, as `extern type` declares one, whose `right` names the function releasing it.
    func parse_handle() -> ast.Node*!:
        let n = try self.node(ast.Kind.extern_type, "")
        _ = self.take()
        n.text = try self.expect_name()
        try self.open_block()
        if not self.at_name("destroy"):
            return try self.fail("a handle names its `destroy` function (§17.7)")
        _ = self.take()
        let destroy = try self.node(ast.Kind.name, "")
        destroy.text = try self.expect_name()
        n.right = destroy
        try self.expect_newline()
        self.skip_newlines()
        if not self.at(token.Kind.dedent):
            return try self.fail("a handle declares `destroy` and nothing else (§17.7)")
        _ = self.take()
        return n

    ## A declaration after its visibility: constant, global, alias, function, or a type.
    func parse_decl(visibility: u32) -> ast.Node*!:
        var flags = visibility
        # `local var`: one variable per thread (§6.3); `local` is a word only there
        if self.at_name("local") and self.peek(1).kind != token.Kind.newline and not self.peek_op(1, ":") and not self.peek_op(1, "="):
            _ = self.take()
            flags |= ast.flag_thread_local
        let attributes = try self.parse_attributes()
        if (flags & ast.flag_thread_local) != 0 and not self.at_kw("var"):
            return try self.fail("`local` declares a `var` (§6.3)")
        if self.at_kw("let"):
            # `linked let NAME: T`: a constant whose storage a library defines (§9.8)
            let linked = names_attribute(attributes, "linked")
            if (attributes != none and not linked) or flags != visibility:
                return try self.fail("an attribute goes before `func` or a top-level `var` (§9.8)")
            let n = try self.node(ast.Kind.constant, "")
            _ = self.take()
            n.text = try self.expect_name()
            if self.eat_op(":"):
                n.ty = try self.parse_type()
            elif linked:
                return try self.fail("a `linked` constant names its type; the library defines its value (§9.8)")
            # a `linked` constant may carry the value the library gives it, for what reads
            # a declaration's initialiser; the program neither stores nor folds it
            if self.eat_op("="):
                n.left = try self.parse_expression()
            elif not linked:
                return try self.fail("a constant needs a value")
            try self.expect_newline()
            n.flags |= flags
            n.attrs = attributes
            return n
        if self.at_kw("var"):
            let n = try self.node(ast.Kind.global, "")
            _ = self.take()
            n.text = try self.expect_name()
            try self.expect_op(":")
            n.ty = try self.parse_type()
            if self.eat_op("="):
                if self.eat_op("---"):
                    n.flags |= ast.flag_uninit
                else:
                    n.left = try self.parse_expression()
            try self.expect_newline()
            n.flags |= flags
            n.attrs = attributes
            return n
        if attributes != none and not (self.at_kw("func") or self.at_kw("static")):
            return try self.fail("an attribute goes before `func` or a top-level `var` (§9.8)")
        if self.at_kw("type"):
            let n = try self.node(ast.Kind.type_alias, "")
            _ = self.take()
            n.text = try self.expect_name()
            try self.expect_op("=")
            n.ty = try self.parse_type()
            try self.expect_newline()
            n.flags |= flags
            return n
        var layout: ast.Node*? = none
        if self.at_name("packed"):
            _ = self.take()
            flags |= ast.flag_packed
        elif self.at_name("align") and self.peek_op(1, "("):
            _ = self.take()
            try self.expect_op("(")
            layout = try self.parse_expression()
            try self.expect_op(")")
        if self.at_kw("struct"):
            let n = try self.parse_struct(false)
            n.flags |= flags
            n.right = layout
            return n
        if self.at_kw("enum"):
            let n = try self.parse_enum()
            n.flags |= flags
            return n
        if self.at_kw("union"):
            let n = try self.parse_union(false)
            n.flags |= flags
            return n
        if self.at_kw("interface"):
            let n = try self.parse_interface()
            n.flags |= flags
            return n
        if self.at_kw("func") or self.at_kw("static"):
            let n = try self.parse_func(names_attribute(attributes, "linked"), false)
            n.flags |= flags
            n.attrs = attributes
            return n
        if self.at_name("class"):
            return try self.fail("`class` belongs to full Luce; Base declares a `struct`")
        return try self.fail("expected a declaration")

    ## Whether the next token is one of the attribute words of §9.8.
    func at_attribute() -> bool:
        if not self.at(token.Kind.name):
            return false
        let word = self.text_of(self.cur())
        return word == "inline" or word == "noinline" or word == "cold" or word == "naked" or word == "weak" or word == "used" or word == "section" or word == "linked"

    func parse_attributes() -> ast.Node*?!:
        var list: ast.Node*? = none
        var tail: ast.Node*? = none
        while self.at_attribute():
            let word = self.text_of(self.cur())
            if true:
                let a = try self.node(ast.Kind.attribute, word)
                _ = self.take()
                if word == "section":
                    try self.expect_op("(")
                    a.left = try self.parse_primary()
                    try self.expect_op(")")
                ast.append(&list, &tail, a)
            else:
                break
        return list

    func parse_import() -> ast.Node*!:
        if self.eat_kw("from"):
            let n = try self.node(ast.Kind.from_import, "")
            n.text = try self.parse_module_path()
            try self.expect_kw("import")
            var tail: ast.Node*? = none
            while true:
                let item = try self.node(ast.Kind.name, "")
                item.text = try self.expect_name()
                if self.eat_kw("as"):
                    let alias = try self.node(ast.Kind.name, "")
                    alias.text = try self.expect_name()
                    item.left = alias
                ast.append(&n.body, &tail, item)
                if not self.eat_op(","):
                    break
            try self.expect_newline()
            return n
        let n = try self.node(ast.Kind.import_, "")
        try self.expect_kw("import")
        n.text = try self.parse_module_path()
        if self.eat_kw("as"):
            let alias = try self.node(ast.Kind.name, "")
            alias.text = try self.expect_name()
            n.left = alias
        try self.expect_newline()
        return n

    func parse_module_path() -> str!:
        let first = self.cur()
        if first.kind != token.Kind.name:
            _ = try self.fail("expected a module path")
        var last = self.take()
        while self.at_op(".") and self.peek(1).kind == token.Kind.name:
            _ = self.take()
            last = self.take()
        return self.src.text(first.start, last.end)

    ## A function: its signature and its suite, or the signature alone when it is `linked`
    ## (§9.8), whose definition a library supplies. `static func` declares a function of a
    ## type, with no receiver (§9.5).
    func parse_func(linked: bool, in_type: bool) -> ast.Node*!:
        let n = try self.node(ast.Kind.func_, "")
        if self.eat_kw("static"):
            n.flags |= ast.flag_static
        try self.expect_kw("func")
        # a method is a member: it binds no name, so a core name is open to it (§3.5)
        n.text = try self.expect_unscoped_name() if in_type else try self.expect_name()
        if self.at_op("["):
            n.left = try self.parse_generic_params()
        # params live in `right`; the suite in `body`
        n.right = try self.parse_params(linked and in_type)
        try self.parse_result(n)
        if linked:
            if self.at_op(":"):
                return try self.fail("a `linked` function has no body; the library defines it (§9.8)")
            try self.expect_newline()
            if in_type:
                try self.linked_receiver(n)
            return n
        try self.expect_op(":")
        n.body = try self.parse_suite()
        return n

    ## A `linked` method has no body to read, so its signature says what one would (§9.8):
    ## a first parameter `self: T*` when it changes its receiver, `self: const T*` when it
    ## reads it. A `static` one is a function of the type `T` and has none.
    func linked_receiver(n: ast.Node*) -> !:
        if let first = n.right:
            if first.text == "self":
                if n.has(ast.flag_static):
                    _ = try self.fail_at(first, "a `static` function has no receiver; `self` names a method's (§9.8)")
                var reads_only = false
                var spelled_right = false
                if let t = first.ty:
                    if let pointee = t.left:
                        spelled_right = t.has(ast.flag_star) and pointee.text == self.member_of and pointee.body == none
                        reads_only = pointee.has(ast.flag_const)
                if not spelled_right:
                    _ = try self.fail_at(first, try self.spelled("`self` is a pointer to its type, `T*` or `const T*`: ", self.member_of))
                if not reads_only:
                    n.flags |= ast.flag_mutating
                n.right = first.next
                return
        if not n.has(ast.flag_static):
            _ = try self.fail_at(n, "a `linked` method names its receiver first, `self: T*` or `self: const T*`; a function of the type is `static` (§9.8)")

    ## A function signature line inside an interface.
    func parse_func_sig() -> ast.Node*!:
        let n = try self.node(ast.Kind.func_, "")
        try self.expect_kw("func")
        n.text = try self.expect_unscoped_name()
        if self.at_op("["):
            n.left = try self.parse_generic_params()
        n.right = try self.parse_params()
        try self.parse_result(n)
        try self.expect_newline()
        return n

    func parse_result(n: ast.Node*) -> !:
        if self.eat_op("->"):
            if self.eat_op("!"):
                n.flags |= ast.flag_fallible
                return
            n.ty = try self.parse_type()

    func parse_generic_params() -> ast.Node*!:
        let list = try self.node(ast.Kind.generic_param, "")
        try self.expect_op("[")
        var tail: ast.Node*? = none
        while not self.at_op("]"):
            let p = try self.node(ast.Kind.generic_param, "")
            p.text = try self.expect_name()
            if self.eat_op(":"):
                var btail: ast.Node*? = none
                while true:
                    let bound = try self.parse_type()
                    ast.append(&p.body, &btail, bound)
                    if not self.eat_op("&"):
                        break
            ast.append(&list.body, &tail, p)
            if not self.eat_op(","):
                break
        try self.expect_op("]")
        return list

    func parse_params(receiver: bool = false) -> ast.Node*?!:
        try self.expect_op("(")
        var list: ast.Node*? = none
        var tail: ast.Node*? = none
        while not self.at_op(")"):
            let p = try self.node(ast.Kind.param, "")
            if self.at_name("out") and self.peek(1).kind == token.Kind.name and self.peek_op(2, ":"):
                _ = self.take()
                p.flags |= ast.flag_out
            if receiver and list == none and self.at_kw("self"):
                # a `linked` method's receiver (§9.8)
                _ = self.take()
                p.text = "self"
            else:
                p.text = try self.expect_name()
            try self.expect_op(":")
            if self.at_name("noalias"):
                _ = self.take()
                p.flags |= ast.flag_noalias
            p.ty = try self.parse_type()
            if self.eat_op("="):
                p.left = try self.parse_expression()
            ast.append(&list, &tail, p)
            if not self.eat_op(","):
                break
        try self.expect_op(")")
        return list

    ## `: A, B` before a type's body (§14.1): the first colon opens the interface list, or
    ## the body when a newline follows it; a list ends with the body's own colon. Both
    ## colons are consumed here.
    func parse_conformance() -> ast.Node*?!:
        try self.expect_op(":")
        if self.at(token.Kind.newline):
            return none
        var list: ast.Node*? = none
        var tail: ast.Node*? = none
        while true:
            let i = try self.parse_type()
            ast.append(&list, &tail, i)
            if not self.eat_op(","):
                break
        try self.expect_op(":")
        return list

    ## `struct Name[T]: A, B:` and the members; `extern struct` has fields only.
    func parse_struct(is_extern: bool) -> ast.Node*!:
        let n = try self.node(ast.Kind.extern_struct if is_extern else ast.Kind.struct_, "")
        try self.expect_kw("struct")
        n.text = try self.expect_name()
        if self.at_op("["):
            n.left = try self.parse_generic_params()
        n.ty = try self.parse_conformance()
        try self.expect_newline()
        try self.expect_indent()
        let outer = self.member_of
        self.member_of = n.text
        defer self.member_of = outer
        var tail: ast.Node*? = none
        while self.block_continues():
            let m = try self.parse_member(is_extern)
            ast.append(&n.body, &tail, m)
        _ = self.take()
        return n

    ## From the `open` bracket at lookahead `*i` to just past its partner `close`, nested
    ## pairs included; false when the source ends first.
    func skip_bracketed(i: usize*, open: str, close: str) -> bool:
        var depth: usize = 1
        *i += 1
        while depth > 0:
            let inner = self.peek(*i)
            if inner.kind == token.Kind.eof:
                return false
            if inner.kind == token.Kind.operator:
                let text = self.text_of(inner)
                if text == open:
                    depth += 1
                elif text == close:
                    depth -= 1
            *i += 1
        return true

    ## `:`, the end of the line and an indent: the start of an indented block of members,
    ## cases or statements.
    func open_block() -> !:
        try self.expect_op(":")
        try self.expect_newline()
        try self.expect_indent()

    ## Whether the indented block goes on: the blank lines and doc comments between its
    ## entries are passed over, and it ends at its dedent or at the end of the source.
    func block_continues() -> bool:
        while self.at(token.Kind.newline) or self.at(token.Kind.doc_comment):
            _ = self.take()
        return not self.at(token.Kind.dedent) and not self.at(token.Kind.eof)

    func expect_indent() -> !:
        if not self.at(token.Kind.indent):
            _ = try self.fail("expected an indented block")
        _ = self.take()

    ## A field or a method inside a struct, enum, or union, beginning at its first word.
    func parse_member(fields_only: bool) -> ast.Node*!:
        let first = self.cur()
        let m = try self.parse_member_words(fields_only)
        if m.start > first.start:
            m.start = first.start
            m.line = first.line
        return m

    func parse_member_words(fields_only: bool) -> ast.Node*!:
        var flags: u32 = 0
        if self.eat_kw("pub"):
            flags |= ast.flag_pub
        if self.eat_export():
            flags |= ast.flag_export
        # a field may be named like an attribute word: `used: u32` is a field, `used func` an attribute
        var attributes: ast.Node*? = none
        if self.at_attribute() and not self.peek_op(1, ":") and not self.peek_op(1, "="):
            attributes = try self.parse_attributes()
        if not fields_only and (self.at_kw("func") or self.at_kw("static")):
            let f = try self.parse_func(names_attribute(attributes, "linked"), true)
            f.flags |= flags
            f.attrs = attributes
            return f
        if attributes != none:
            return try self.fail("an attribute goes before a method (§9.8)")
        let field = try self.node(ast.Kind.field, "")
        if self.at_name("align") and self.peek_op(1, "("):
            _ = self.take()
            try self.expect_op("(")
            field.right = try self.parse_expression()
            try self.expect_op(")")
        if self.eat_kw("var"):
            flags |= 0
        elif self.eat_kw("let"):
            flags |= ast.flag_const
        elif self.at_name("class"):
            return try self.fail("`class` belongs to full Luce; a struct nests no types, declare it beside (§20)")
        elif not fields_only:
            _ = try self.fail("expected `var`, `let`, or `func`")
        field.text = try self.expect_unscoped_name()
        try self.expect_op(":")
        field.ty = try self.parse_type()
        if self.eat_op("="):
            field.left = try self.parse_expression()
        try self.expect_newline()
        field.flags |= flags
        return field

    func parse_enum() -> ast.Node*!:
        let n = try self.node(ast.Kind.enum_, "")
        try self.expect_kw("enum")
        n.text = try self.expect_name()
        if self.at_op("["):
            n.left = try self.parse_generic_params()
        if self.eat_kw("as"):
            n.ty = try self.parse_type()
        n.right = try self.parse_conformance()
        try self.expect_newline()
        try self.expect_indent()
        let outer = self.member_of
        self.member_of = n.text
        defer self.member_of = outer
        var tail: ast.Node*? = none
        while self.block_continues():
            let method_ahead = self.at_kw("pub") or self.at_kw("static") or (self.at_attribute() and not self.peek_op(1, "=") and not self.peek_op(1, ":")) or (self.at_kw("func") and self.peek(1).kind == token.Kind.name)
            if method_ahead:
                let m = try self.parse_member(false)
                ast.append(&n.body, &tail, m)
                continue
            let case_node = try self.node(ast.Kind.enum_case, "")
            case_node.text = try self.expect_unscoped_name()
            if self.at_op("("):
                case_node.body = try self.parse_params()
            elif self.eat_op("="):
                case_node.left = try self.parse_expression()
            try self.expect_newline()
            ast.append(&n.body, &tail, case_node)
        _ = self.take()
        return n

    func parse_union(is_extern: bool) -> ast.Node*!:
        let n = try self.node(ast.Kind.extern_union if is_extern else ast.Kind.union_, "")
        try self.expect_kw("union")
        n.text = try self.expect_name()
        try self.open_block()
        let outer = self.member_of
        self.member_of = n.text
        defer self.member_of = outer
        var tail: ast.Node*? = none
        while self.block_continues():
            let pub_member = self.at_kw("pub") and self.peek(1).kind == token.Kind.name and self.peek_op(2, ":")
            if not is_extern and not pub_member and (self.at_kw("pub") or self.at_kw("func") or self.at_kw("static")):
                let m = try self.parse_member(false)
                ast.append(&n.body, &tail, m)
                continue
            let member = try self.node(ast.Kind.field, "")
            if pub_member:
                _ = self.take()
                member.flags |= ast.flag_pub
            member.text = try self.expect_unscoped_name()
            try self.expect_op(":")
            member.ty = try self.parse_type()
            try self.expect_newline()
            ast.append(&n.body, &tail, member)
        _ = self.take()
        return n

    func parse_interface() -> ast.Node*!:
        let n = try self.node(ast.Kind.interface_, "")
        try self.expect_kw("interface")
        n.text = try self.expect_name()
        if self.at_op("["):
            n.left = try self.parse_generic_params()
        try self.open_block()
        var tail: ast.Node*? = none
        while self.block_continues():
            let sig = try self.parse_func_sig()
            ast.append(&n.body, &tail, sig)
        _ = self.take()
        return n

    func parse_test() -> ast.Node*!:
        let n = try self.node(ast.Kind.test_, "")
        try self.expect_kw("test")
        if not self.at(token.Kind.text):
            _ = try self.fail("a test needs a title")
        n.text = self.text_of(self.take())
        try self.expect_op(":")
        n.body = try self.parse_suite()
        return n

    func parse_extern() -> ast.Node*!:
        try self.expect_kw("extern")
        if self.at_kw("type"):
            let n = try self.node(ast.Kind.extern_type, "")
            _ = self.take()
            n.text = try self.expect_name()
            if self.eat_op("="):
                n.ty = try self.parse_type()
            try self.expect_newline()
            return n
        if self.at_kw("var"):
            let n = try self.node(ast.Kind.extern_var, "")
            _ = self.take()
            n.text = try self.expect_name()
            try self.expect_op(":")
            n.ty = try self.parse_type()
            try self.expect_newline()
            return n
        if self.at_kw("struct") or self.at_name("packed") or (self.at_name("align") and self.peek_op(1, "(")):
            var flags: u32 = 0
            var layout: ast.Node*? = none
            if self.at_name("packed"):
                _ = self.take()
                flags |= ast.flag_packed
            elif self.at_name("align"):
                _ = self.take()
                try self.expect_op("(")
                layout = try self.parse_expression()
                try self.expect_op(")")
            let n = try self.parse_struct(true)
            n.flags |= flags
            n.right = layout
            return n
        if self.at_kw("union"):
            return try self.parse_union(true)
        let n = try self.node(ast.Kind.extern_func, "")
        if self.at_name("blocking"):
            _ = self.take()
            n.flags |= ast.flag_blocking
        try self.expect_kw("func")
        n.text = try self.expect_name()
        if self.eat_kw("as"):
            if not self.at(token.Kind.text):
                _ = try self.fail("expected the C symbol as a string")
            n.left = try self.taken(ast.Kind.literal)
        try self.expect_op("(")
        var tail: ast.Node*? = none
        while not self.at_op(")"):
            if self.eat_op("..."):
                n.flags |= ast.flag_variadic
                break
            let p = try self.node(ast.Kind.param, "")
            if self.at_name("out"):
                _ = self.take()
                p.flags |= ast.flag_out
            p.text = try self.expect_unscoped_name()
            try self.expect_op(":")
            p.ty = try self.parse_type()
            ast.append(&n.right, &tail, p)
            if not self.eat_op(","):
                break
        try self.expect_op(")")
        try self.parse_result(n)
        try self.expect_newline()
        return n

    ## `asm ARCH:` with raw lines, at module level or as a statement.
    func parse_asm() -> ast.Node*!:
        let n = try self.node(ast.Kind.asm_, "")
        try self.expect_kw("asm")
        n.text = try self.expect_name()
        if self.eat_op("("):
            var tail: ast.Node*? = none
            while not self.at_op(")"):
                let operand = try self.node(ast.Kind.argument, "")
                operand.text = self.text_of(self.take())  # in / out / inout / options
                try self.expect_op("(")
                var ptail: ast.Node*? = none
                while not self.at_op(")"):
                    let place = try self.taken(ast.Kind.literal)
                    ast.append(&operand.body, &ptail, place)
                    if not self.eat_op(","):
                        break
                try self.expect_op(")")
                if operand.text != "options":
                    if self.at_name("_"):
                        operand.left = try self.taken(ast.Kind.name)
                    else:
                        operand.left = try self.parse_expression()
                ast.append(&n.right, &tail, operand)
                if not self.eat_op(","):
                    break
            try self.expect_op(")")
        try self.open_block()
        var tail: ast.Node*? = none
        while self.at(token.Kind.raw_line):
            let line = try self.taken(ast.Kind.literal)
            ast.append(&n.body, &tail, line)
        if not self.at(token.Kind.dedent):
            _ = try self.fail("an asm suite holds raw lines only")
        _ = self.take()
        return n

    # -- statements -----------------------------------------------------------------------

    ## `:` was consumed; a same-line simple statement or an indented block.
    func parse_suite() -> ast.Node*!:
        let block = try self.node(ast.Kind.block, "")
        var tail: ast.Node*? = none
        if not self.at(token.Kind.newline):
            if self.at_compound_statement():
                return try self.fail("a same-line suite cannot contain a compound statement (§3.2)")
            let s = try self.parse_simple_statement()
            ast.append(&block.body, &tail, s)
            return block
        _ = self.take()
        try self.expect_indent()
        try self.enter()
        while self.block_continues():
            let s = try self.parse_statement()
            ast.append(&block.body, &tail, s)
        if self.at(token.Kind.dedent):
            _ = self.take()
        self.leave()
        return block

    ## `if`, `while`, `for`, `match`, `with`, `asm`: what a same-line suite may not hold.
    func at_compound_statement() -> bool:
        return self.at_kw("if") or self.at_kw("while") or self.at_kw("for") or self.at_kw("match") or self.at_kw("with") or self.at_kw("asm")

    func parse_statement() -> ast.Node*!:
        if self.at_kw("try") and self.peek_op(1, ":"):
            return try self.fail("a `try:` block belongs to full Luce; Base writes `catch` after an expression (§11.3)")
        if self.at_kw("if"):
            return try self.parse_if()
        if self.at_kw("while"):
            return try self.parse_while("")
        if self.at_kw("for"):
            return try self.parse_for("")
        if self.at_kw("match"):
            return try self.parse_match(false)
        if self.at_kw("with"):
            let n = try self.node(ast.Kind.with_, "")
            _ = self.take()
            n.left = try self.parse_expression()
            try self.expect_op(":")
            n.body = try self.parse_suite()
            return n
        if self.at_kw("asm"):
            return try self.parse_asm()
        if self.at(token.Kind.name) and self.peek_op(1, ":"):
            let label = self.text_of(self.take())
            _ = self.take()
            if self.at_kw("while"):
                return try self.parse_while(label)
            if self.at_kw("for"):
                return try self.parse_for(label)
            _ = try self.fail("a label must be followed by a loop")
        return try self.parse_simple_statement()

    func parse_simple_statement() -> ast.Node*!:
        if self.at_name("spawn"):
            return try self.fail("`spawn` belongs to full Luce; Base starts a thread through the `thread` module")
        if self.at_kw("let") or self.at_kw("var"):
            return try self.parse_binding()
        if self.at_kw("break") or self.at_kw("continue"):
            let is_break = self.at_kw("break")
            let n = try self.node(ast.Kind.break_ if is_break else ast.Kind.continue_, "")
            _ = self.take()
            if self.at(token.Kind.name):
                n.text = self.text_of(self.take())
            try self.expect_newline()
            return n
        if self.at_kw("return"):
            let n = try self.node(ast.Kind.return_, "")
            _ = self.take()
            # a bare `return` may end a handler written inside parentheses (§11.4)
            if not self.at(token.Kind.newline) and not self.at(token.Kind.dedent) and not self.at(token.Kind.eof) and not self.at_op(")"):
                n.left = try self.parse_expression()
            try self.expect_newline()
            return n
        if self.at_kw("defer") or self.at_kw("errdefer"):
            let is_defer = self.at_kw("defer")
            let n = try self.node(ast.Kind.defer_ if is_defer else ast.Kind.errdefer_, "")
            _ = self.take()
            # `defer: suite` or `defer statement`: either way a block, run as the scope is left
            if self.eat_op(":"):
                n.body = try self.parse_suite()
                return n
            if self.at_compound_statement():
                return try self.fail("a deferred compound statement is written as a block: `defer:` (§8.8)")
            let block = try self.node(ast.Kind.block, "")
            block.body = try self.parse_simple_statement()
            n.body = block
            return n
        if self.at_kw("recover"):
            let n = try self.node(ast.Kind.recover_, "")
            _ = self.take()
            n.left = try self.parse_expression()
            try self.expect_newline()
            return n
        if self.at_kw("free"):
            return try self.parse_free()
        let e = try self.parse_expression()
        if self.at(token.Kind.operator) and is_assign_op(self.text_of(self.cur())):
            let n = try self.taken(ast.Kind.assign)
            n.left = e
            n.right = try self.parse_expression()
            try self.expect_newline()
            return n
        let n = try self.node(ast.Kind.expr_stmt, "")
        n.left = e
        if e.kind != ast.Kind.catch_:
            try self.expect_newline()
        return n

    func parse_free() -> ast.Node*!:
        let n = try self.node(ast.Kind.free_, "")
        try self.expect_kw("free")
        try self.expect_op("(")
        n.left = try self.parse_expression()
        try self.expect_op(")")
        if self.eat_kw("in"):
            n.right = try self.parse_else()  # a `catch` after the allocator handles the allocation
        try self.expect_newline()
        return n

    ## `let`/`var` with a name or a tuple pattern, a type, and an initialiser or `---`.
    func parse_binding() -> ast.Node*!:
        let is_let = self.at_kw("let")
        let n = try self.node(ast.Kind.let_ if is_let else ast.Kind.var_, "")
        _ = self.take()
        if self.eat_op("("):
            var tail: ast.Node*? = none
            while not self.at_op(")"):
                let name = try self.node(ast.Kind.name, "")
                name.text = try self.expect_name()
                ast.append(&n.body, &tail, name)
                if not self.eat_op(","):
                    break
            try self.expect_op(")")
        else:
            n.text = try self.expect_name()
        if self.eat_op(":"):
            n.ty = try self.parse_type()
        if self.eat_op("="):
            if self.eat_op("---"):
                n.flags |= ast.flag_uninit
            else:
                n.left = try self.parse_expression()
        elif is_let:
            _ = try self.fail("a let binding requires an initialiser")
        try self.expect_newline()
        return n

    ## `expression` or `let NAME = expression` after if/while/elif.
    func parse_condition(n: ast.Node*) -> !:
        if self.eat_kw("let"):
            n.flags |= ast.flag_if_let
            let binding = try self.node(ast.Kind.let_, "")
            binding.text = try self.expect_name()
            try self.expect_op("=")
            binding.left = try self.parse_expression()
            n.left = binding
            return
        n.left = try self.parse_expression()

    func parse_if() -> ast.Node*!:
        let n = try self.node(ast.Kind.if_, "")
        _ = self.take()
        try self.parse_condition(n)
        try self.expect_op(":")
        n.body = try self.parse_suite()
        if self.at_kw("elif"):
            let rest = try self.parse_if()  # `elif` reads as a nested if
            n.right = rest
        elif self.eat_kw("else"):
            try self.expect_op(":")
            n.right = try self.parse_suite()
        return n

    func parse_while(label: str) -> ast.Node*!:
        let n = try self.node(ast.Kind.while_, label)
        try self.expect_kw("while")
        try self.parse_condition(n)
        try self.expect_op(":")
        n.body = try self.parse_suite()
        return n

    func parse_for(label: str) -> ast.Node*!:
        let n = try self.node(ast.Kind.for_, label)
        try self.expect_kw("for")
        let binding = try self.node(ast.Kind.let_, "")
        if self.eat_op("("):
            var tail: ast.Node*? = none
            while not self.at_op(")"):
                let name = try self.node(ast.Kind.name, "")
                name.text = try self.expect_name()
                ast.append(&binding.body, &tail, name)
                if not self.eat_op(","):
                    break
            try self.expect_op(")")
        else:
            binding.text = try self.expect_name()
            if self.eat_op(":"):
                binding.ty = try self.parse_type()
        n.left = binding
        try self.expect_kw("in")
        if self.eat_op("&"):
            n.flags |= ast.flag_by_pointer
        n.right = try self.parse_expression()
        try self.expect_op(":")
        n.body = try self.parse_suite()
        return n

    ## `match` as a statement (arms with `:` suites) or an expression (arms with `=>`).
    func parse_match(is_expr: bool) -> ast.Node*!:
        let n = try self.node(ast.Kind.match_expr if is_expr else ast.Kind.match_, "")
        try self.expect_kw("match")
        n.left = try self.parse_expression()
        try self.open_block()
        var tail: ast.Node*? = none
        while self.block_continues():
            let arm = try self.node(ast.Kind.match_arm, "")
            var ptail: ast.Node*? = none
            while true:
                let p = try self.parse_pattern()
                ast.append(&arm.left, &ptail, p)
                if not self.eat_op(","):
                    break
            if self.eat_kw("if"):
                arm.right = try self.parse_expression()
            if is_expr:
                try self.expect_op("=>")
                arm.body = try self.parse_expression()
                try self.expect_newline()
            else:
                try self.expect_op(":")
                arm.body = try self.parse_suite()
            ast.append(&n.body, &tail, arm)
        _ = self.take()
        return n

    func parse_pattern() -> ast.Node*!:
        let p = try self.node(ast.Kind.pattern, "")
        if self.at_name("_"):
            _ = self.take()
            p.flags |= ast.flag_wildcard
            return p
        if self.eat_op("."):
            let value = try self.node(ast.Kind.case_value, "")
            value.text = try self.expect_member_name()
            if self.eat_op("("):
                var tail: ast.Node*? = none
                while not self.at_op(")"):
                    let b = try self.taken(ast.Kind.name)
                    ast.append(&value.body, &tail, b)
                    if not self.eat_op(","):
                        break
                try self.expect_op(")")
            p.left = value
            return p
        p.left = try self.parse_pattern_literal()
        if self.at_op("..<") or self.at_op("..="):
            p.text = self.text_of(self.take())
            p.right = try self.parse_pattern_literal()
        return p

    func parse_pattern_literal() -> ast.Node*!:
        if self.at_op("-"):
            let neg = try self.taken(ast.Kind.unary)
            neg.left = try self.parse_primary()
            return neg
        return try self.parse_primary()

    # -- expressions ----------------------------------------------------------------------
    pub func parse_expression() -> ast.Node*!:
        try self.enter()
        var e = try self.parse_else()
        if self.at_kw("catch") and not self.ended_suite():
            let handler = try self.node(ast.Kind.catch_, "")
            _ = self.take()
            if self.at(token.Kind.name):
                handler.text = self.text_of(self.take())
            try self.expect_op(":")
            handler.left = e
            handler.body = try self.parse_suite()
            e = handler
        self.leave()
        return e

    func parse_else() -> ast.Node*!:
        # A leading marker covers the conditional and fallback, stopping before
        # an attached catch. Infix arithmetic keeps its ordinary precedence.
        if self.at_kw("try"):
            let marked = try self.taken(ast.Kind.unary)
            try self.enter()
            marked.left = try self.parse_else()
            self.leave()
            return marked
        let e = try self.parse_conditional()
        if self.at_kw("else") and not self.ended_suite():
            let n = try self.node(ast.Kind.else_, "")
            _ = self.take()
            n.left = e
            if self.at_kw("return") or self.at_kw("break") or self.at_kw("continue"):
                n.right = try self.parse_simple_exit()
            else:
                n.right = try self.parse_else()
            return n
        return e

    ## `else return x`, `else break`: an exit inside an expression.
    func parse_simple_exit() -> ast.Node*!:
        if self.at_kw("return"):
            let n = try self.node(ast.Kind.return_, "")
            _ = self.take()
            if not self.at(token.Kind.newline) and not self.at(token.Kind.dedent) and not self.at(token.Kind.eof) and not self.at_op(")"):
                n.left = try self.parse_expression()
            return n
        let is_break = self.at_kw("break")
        let n = try self.node(ast.Kind.break_ if is_break else ast.Kind.continue_, "")
        _ = self.take()
        if self.at(token.Kind.name):
            n.text = self.text_of(self.take())
        return n

    func parse_conditional() -> ast.Node*!:
        let value = try self.parse_binary(0)
        if self.at_kw("if") and not self.ended_suite():
            let n = try self.node(ast.Kind.conditional, "")
            _ = self.take()
            n.left = value
            n.ty = try self.parse_binary(0)
            try self.expect_kw("else")
            n.right = try self.parse_conditional()
            return n
        return value

    ## Precedence levels, lowest first: or, and, comparison, range, |, ^, &, shifts, additive, multiplicative.
    func level_of(t: token.Token) -> u32:
        if t.kind == token.Kind.keyword:
            let w = self.text_of(t)
            if w == "or":
                return 1
            if w == "and":
                return 2
            return 0
        if t.kind != token.Kind.operator:
            return 0
        let s = self.text_of(t)
        if s == "==" or s == "!=" or s == "<" or s == "<=" or s == ">" or s == ">=":
            return 3
        if s == "..<" or s == "..=":
            return 4
        if s == "|":
            return 5
        if s == "^":
            return 6
        if s == "&":
            return 7
        if s == "<<" or s == ">>":
            return 8
        if s == "+" or s == "-" or s == "+%" or s == "-%" or s == "+|" or s == "-|" or s == "+?" or s == "-?":
            return 9
        if s == "*" or s == "/" or s == "//" or s == "%" or s == "*%" or s == "*|" or s == "*?":
            return 10
        return 0

    func parse_binary(min_level: u32) -> ast.Node*!:
        var left = try self.parse_unary()
        var chain: u32 = 0
        while not self.ended_suite():
            let t = self.cur()
            let level = self.level_of(t)
            if level == 0 or level <= min_level:
                break
            # an operator chain deepens the tree by one level per operator
            chain += 1
            if self.nest + chain > max_chain:
                _ = try self.fail("the source nests too deeply")
            let n = try self.taken(ast.Kind.binary)
            n.left = left
            # comparison and range do not chain (§7.3)
            n.right = try self.parse_binary(level if level != 3 and level != 4 else level)
            left = n
            if level == 3 or level == 4:
                if self.level_of(self.cur()) == level:
                    _ = try self.fail("comparisons do not chain; use `and`")
        return left

    func parse_unary() -> ast.Node*!:
        try self.enter()
        let n = try self.parse_unary_inner()
        self.leave()
        return n

    func parse_unary_inner() -> ast.Node*!:
        if self.at_kw("try") or self.at_kw("not"):
            let n = try self.taken(ast.Kind.unary)
            n.left = try self.parse_unary()
            return n
        if self.at_op("-") or self.at_op("-%") or self.at_op("~") or self.at_op("*") or self.at_op("&") or self.at_op("+"):
            let n = try self.taken(ast.Kind.unary)
            n.left = try self.parse_unary()
            return n
        if self.at_op("(") and self.looks_like_cast():
            let n = try self.node(ast.Kind.cast, "")
            _ = self.take()
            n.ty = try self.parse_type()
            try self.expect_op(")")
            n.left = try self.parse_unary()
            return n
        return try self.parse_postfix()

    ## `(T)x`: the parenthesised text names a type and is followed by an operand (§7.5).
    func looks_like_cast() -> bool:
        # `(func(A, B) -> R)expr`: a function-pointer cast (§7.5), the way `objc_msgSend`
        # is called with one C symbol and many shapes
        let first = self.peek(1)
        if first.kind == token.Kind.keyword and self.text_of(first) == "func":
            var depth: usize = 1
            var j: usize = 1
            while depth > 0 and j < 512:
                let tk = self.peek(j)
                if tk.kind == token.Kind.eof:
                    return false
                if tk.kind == token.Kind.operator:
                    let s = self.text_of(tk)
                    if s == "(":
                        depth += 1
                    elif s == ")":
                        depth -= 1
                        if depth == 0:
                            break
                j += 1
            return self.cast_operand_follows(j + 1)
        var i: usize = 1
        var t = self.peek(i)
        if t.kind == token.Kind.operator and self.text_of(t) == "@":
            i += 1
            t = self.peek(i)
        var qualified = false
        while t.kind == token.Kind.keyword and (self.text_of(t) == "const" or self.text_of(t) == "volatile"):
            qualified = true
            i += 1
            t = self.peek(i)
        var head = ""
        var typed = false
        var bare = false
        if qualified and t.kind == token.Kind.operator and self.text_of(t) == "(":
            # `(const (T*)*)p`: a parenthesised pointer type after a qualifier, C's
            # `T *const *` (§5.3); `((x))` alone is a grouped expression
            if not self.skip_bracketed(&i, "(", ")"):
                return false
            typed = true
        else:
            if t.kind != token.Kind.name:
                return false
            head = self.text_of(t)
            typed = is_type_word(head)
            bare = not typed  # a lowercase name: an alias, if anything
            i += 1
        t = self.peek(i)
        while t.kind == token.Kind.operator:
            let s = self.text_of(t)
            if s == "." and self.peek(i + 1).kind == token.Kind.name:
                typed = typed or is_type_word(self.text_of(self.peek(i + 1))) or head == "c"
                bare = not typed
                i += 2
            elif s == "*" or s == "?" or s == "*?":
                typed = true
                i += 1
            elif s == "[" and self.peek_op(i + 1, "]"):
                typed = true
                i += 2
            elif s == "[" and typed:
                # `(List[T]*)p`: the type arguments of a generic instance (§7.5)
                if not self.skip_bracketed(&i, "[", "]"):
                    return false
            else:
                break
            t = self.peek(i)
        if not (t.kind == token.Kind.operator and self.text_of(t) == ")"):
            return false
        if bare:
            # `(bits)1`, `(lib.bits)x`: a cast through an alias only when a plain operand
            # follows, since `(n) - 1` and `(n) * p` are arithmetic (§7.5)
            let after = self.peek(i + 1)
            return after.kind == token.Kind.name or after.kind == token.Kind.integer or after.kind == token.Kind.float or after.kind == token.Kind.character or after.kind == token.Kind.text
        if not typed:
            return false
        return self.cast_operand_follows(i + 1)

    ## What follows a cast's `)` must begin an operand for it to be a cast.
    func cast_operand_follows(at: usize) -> bool:
        let after = self.peek(at)
        if after.kind == token.Kind.name or after.kind == token.Kind.integer or after.kind == token.Kind.float or after.kind == token.Kind.character or after.kind == token.Kind.text or after.kind == token.Kind.format_start:
            return true
        if after.kind == token.Kind.keyword:
            let w = self.text_of(after)
            return w == "self" or w == "try" or w == "not" or w == "true" or w == "false"
        if after.kind == token.Kind.operator:
            let s = self.text_of(after)
            return s == "(" or s == "&" or s == "*" or s == "~" or s == "[" or s == "-" or s == "-%"
        return false

    func parse_postfix() -> ast.Node*!:
        var e = try self.parse_primary()
        # every postfix deepens the tree by one level, and the passes after the parser
        # recurse over that depth: a chain counts like nesting
        var chain: u32 = 0
        while not self.ended_suite():
            chain += 1
            if self.nest + chain > max_chain:
                _ = try self.fail("the source nests too deeply")
            if self.at_op(".") and self.at_member_name(1):
                _ = self.take()
                let m = try self.taken(ast.Kind.member)
                m.left = e
                e = m
            elif self.at_op("("):
                let call = try self.node(ast.Kind.call, "")
                call.left = e
                if names_a_measure(e) and self.type_argument_ahead():
                    call.body = try self.parse_type_argument()
                elif e.kind == ast.Kind.name and e.text == "assert":
                    call.body = try self.parse_assert_arguments(call)
                else:
                    call.body = try self.parse_arguments()
                e = call
            elif self.at_op("[") and (self.looks_like_type_args() or (e.kind == ast.Kind.name and e.ty == none and self.value_type_args_ahead())):
                let args = try self.parse_type_args()
                if self.at_op("("):
                    let call = try self.node(ast.Kind.call, "")
                    call.left = e
                    call.ty = args
                    call.body = try self.parse_arguments()
                    e = call
                else:
                    e.ty = args  # `Map[str, u32].create(...)`
            elif self.at_op("["):
                _ = self.take()
                if self.eat_op("..<"):
                    let s = try self.node(ast.Kind.slice, "")
                    s.left = e
                    s.right = try self.parse_expression()
                    try self.expect_op("]")
                    e = s
                    continue
                let index = try self.parse_expression()
                if index.kind == ast.Kind.binary and index.text == "..<":
                    # `[start..<end]` reads as a range expression; it is a slice
                    let s = try self.node(ast.Kind.slice, "")
                    s.left = e
                    s.body = index.left
                    s.right = index.right
                    s.start = index.start
                    try self.expect_op("]")
                    e = s
                    continue
                if self.at_op("..<") or self.at_op(".."):
                    let s = try self.node(ast.Kind.slice, "")
                    s.left = e
                    s.body = index
                    if self.text_of(self.take()) == "..<":
                        s.right = try self.parse_expression()
                    try self.expect_op("]")
                    e = s
                    continue
                let ix = try self.node(ast.Kind.index, "")
                ix.left = e
                ix.body = index
                try self.expect_op("]")
                e = ix
            else:
                break
        return e

    ## `name[T](...)`: a bracket after a name holding types and followed by `(`.
    func looks_like_type_args() -> bool:
        var i: usize = 1
        var depth: u32 = 1
        while depth > 0:
            let t = self.peek(i)
            if t.kind == token.Kind.eof or t.kind == token.Kind.newline:
                return false
            if t.kind == token.Kind.operator:
                let s = self.text_of(t)
                if s == "[":
                    depth += 1
                elif s == "]":
                    depth -= 1
            i += 1
        let first = self.peek(1)
        if first.kind == token.Kind.keyword:
            let word = self.text_of(first)
            if word == "const" or word == "volatile" or word == "func":
                return self.peek_op(i, "(") or self.peek_op(i, ".")
        if first.kind == token.Kind.operator and self.text_of(first) == "@":
            return self.peek_op(i, "(") or self.peek_op(i, ".")
        if first.kind == token.Kind.operator and self.text_of(first) == "(" and self.tuple_type_at(2):
            # `first[(i64, str)](...)`: a tuple as a type argument (§13)
            return self.peek_op(i, "(") or self.peek_op(i, ".")
        if first.kind != token.Kind.name:
            return false
        if self.bracket_holds_expression():
            return false
        # `module.Type` counts as a type word too
        let qualified = self.peek_op(2, ".") and self.peek(3).kind == token.Kind.name and is_type_word(self.text_of(self.peek(3)))
        if not is_type_word(self.text_of(first)) and not qualified:
            return false
        return self.peek_op(i, "(") or self.peek_op(i, ".")

    ## `f[i64]` or `pick[i32, u64]` used as a value, the function instantiated: a bracket
    ## after a plain name whose content can only be types: `const`, `func`, `@`, a core type
    ## word, a tuple type, or a list with a comma, each starting with a type word that is not
    ## converting (`usize(i)`) or naming a member (`i64.max`, `Kind.a`). A single capitalised
    ## name stays an index here; the checker decides it by what it names (§13).
    func value_type_args_ahead() -> bool:
        let first = self.peek(1)
        if first.kind == token.Kind.keyword:
            let word = self.text_of(first)
            if word == "const" or word == "func":
                return true
        if first.kind == token.Kind.operator and self.text_of(first) == "@":
            return true
        if first.kind == token.Kind.operator and self.text_of(first) == "(":
            return self.tuple_type_at(2) and self.type_word_as_type_at(2)
        if first.kind != token.Kind.name or self.bracket_holds_expression() or not self.type_word_as_type_at(1):
            return false
        let word = self.text_of(first)
        let core: str[20] = ["i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "usize", "isize", "f16", "f32", "f64", "bool", "char", "str", "fmt", "unit", "never", "void"]
        for core_name in core:
            if core_name == word:
                return true
        # a comma at the bracket's own depth: a list of types, never an index
        var i: usize = 1
        var depth: u32 = 0
        while true:
            let t = self.peek(i)
            if t.kind == token.Kind.eof or t.kind == token.Kind.newline:
                return false
            if t.kind == token.Kind.operator:
                let s = self.text_of(t)
                if s == "(" or s == "[":
                    depth += 1
                elif s == ")" or s == "]":
                    if depth == 0:
                        return false
                    depth -= 1
                elif s == "," and depth == 0:
                    return true
            i += 1
        return false

    ## Whether the token at `at` is a type word (a core type or a capitalised name) not
    ## followed by `(` or `.`, which would make it a conversion or a member: a value. A nested
    ## `(` is left to the caller.
    func type_word_as_type_at(at: usize) -> bool:
        let t = self.peek(at)
        if t.kind == token.Kind.operator and self.text_of(t) == "(":
            return true
        if t.kind != token.Kind.name or not is_type_word(self.text_of(t)):
            return false
        let after = self.peek(at + 1)
        return not (after.kind == token.Kind.operator and (self.text_of(after) == "(" or self.text_of(after) == "."))

    ## Whether a tuple type opens at `at`, just after a `(`: a type word, or a nested `(`
    ## opening one, then a comma at the same depth before the close.
    func tuple_type_at(at: usize) -> bool:
        let t = self.peek(at)
        if t.kind == token.Kind.operator and self.text_of(t) == "(":
            return self.tuple_type_at(at + 1)
        if t.kind != token.Kind.name or not (is_type_word(self.text_of(t)) or self.qualified_type_ahead(at)):
            return false
        var j = at + 1
        var depth: u32 = 0
        while j < at + 64:
            let k = self.peek(j)
            if k.kind == token.Kind.eof or k.kind == token.Kind.newline:
                return false
            if k.kind == token.Kind.operator:
                let s = self.text_of(k)
                if s == "[" or s == "(":
                    depth += 1
                elif s == "]" or s == ")":
                    if depth == 0:
                        return false
                    depth -= 1
                elif s == "," and depth == 0:
                    return true
            j += 1
        return false

    func parse_type_args() -> ast.Node*!:
        let list = try self.node(ast.Kind.type_, "")
        try self.expect_op("[")
        var tail: ast.Node*? = none
        while not self.at_op("]"):
            let t = try self.parse_type()
            ast.append(&list.body, &tail, t)
            if not self.eat_op(","):
                break
        try self.expect_op("]")
        return list

    ## Whether `memory.size_of(` is followed by a type rather than an expression: a type word,
    ## `module.Type`, a parenthesised type, or `func`, `const`, `volatile` (§5.11).
    func type_argument_ahead() -> bool:
        let t = self.peek(1)
        if t.kind == token.Kind.operator and self.text_of(t) == "@":
            return true
        if t.kind == token.Kind.operator and self.text_of(t) == "(":
            let inner = self.peek(2)
            return inner.kind == token.Kind.name and is_type_word(self.text_of(inner))
        if t.kind == token.Kind.keyword:
            let w = self.text_of(t)
            return w == "func" or w == "const" or w == "volatile"
        return t.kind == token.Kind.name and (is_type_word(self.text_of(t)) or self.qualified_type_ahead(1))

    ## Whether `(` opens a parenthesised type: a type word, `func`, `const`, or `volatile`.
    func paren_type_ahead() -> bool:
        let inner = self.peek(1)
        if inner.kind == token.Kind.keyword:
            let w = self.text_of(inner)
            return w == "func" or w == "const" or w == "volatile"
        return inner.kind == token.Kind.name and (is_type_word(self.text_of(inner)) or self.qualified_type_ahead(1))

    ## `(Type)` or `(Type, field)`: the first argument is a type, the rest are expressions.
    func parse_type_argument() -> ast.Node*?!:
        try self.expect_op("(")
        let first = try self.node(ast.Kind.argument, "")
        first.left = try self.parse_type()
        var list: ast.Node*? = first
        var tail: ast.Node*? = first
        while self.eat_op(","):
            let more = try self.node(ast.Kind.argument, "")
            more.left = try self.parse_expression()
            ast.append(&list, &tail, more)
        try self.expect_op(")")
        return list

    ## `assert(condition)` or `assert(condition, message)`: the arguments, with the
    ## condition's own text kept on the call for the trap's message (§11.6).
    func parse_assert_arguments(call: ast.Node*) -> ast.Node*?!:
        try self.expect_op("(")
        let first = try self.node(ast.Kind.argument, "")
        let begin = self.cur().start
        first.left = try self.parse_expression()
        call.text = self.src.text(begin, self.tokens[self.pos - 1].end)
        var list: ast.Node*? = first
        var tail: ast.Node*? = first
        if self.eat_op(","):
            let more = try self.node(ast.Kind.argument, "")
            more.left = try self.parse_expression()
            ast.append(&list, &tail, more)
        try self.expect_op(")")
        return list

    func parse_arguments() -> ast.Node*?!:
        try self.expect_op("(")
        var list: ast.Node*? = none
        var tail: ast.Node*? = none
        while not self.at_op(")"):
            let a = try self.node(ast.Kind.argument, "")
            if self.at(token.Kind.name) and self.peek_op(1, "="):
                a.text = self.text_of(self.take())
                _ = self.take()
            a.left = try self.parse_expression()
            ast.append(&list, &tail, a)
            if not self.eat_op(","):
                break
        try self.expect_op(")")
        return list

    func parse_primary() -> ast.Node*!:
        let t = self.cur()
        if t.kind == token.Kind.integer or t.kind == token.Kind.float or t.kind == token.Kind.character or t.kind == token.Kind.text or t.kind == token.Kind.bytes or t.kind == token.Kind.raw:
            return try self.taken(ast.Kind.literal)
        if t.kind == token.Kind.format_start:
            return try self.parse_formatted()
        if t.kind == token.Kind.keyword:
            let w = self.text_of(t)
            if w == "true" or w == "false" or w == "none":
                return try self.taken(ast.Kind.literal)
            if w == "self":
                let n = try self.node(ast.Kind.self_, "self")
                _ = self.take()
                return n
            if w == "match":
                return try self.parse_match(true)
            if w == "new":
                return try self.parse_new()
            _ = try self.fail("expected an expression")
        if t.kind == token.Kind.name:
            if self.looks_like_span_constructor():
                let s = try self.node(ast.Kind.span_make, "")
                s.ty = try self.parse_type()
                s.body = try self.parse_arguments()
                return s
            return try self.taken(ast.Kind.name)
        if t.kind == token.Kind.operator:
            let s = self.text_of(t)
            if s == ".":
                let value = try self.node(ast.Kind.case_value, "")
                _ = self.take()
                value.text = try self.expect_member_name()
                if self.at_op("("):
                    value.body = try self.parse_arguments()
                return value
            if s == "[":
                let a = try self.node(ast.Kind.array_lit, "")
                _ = self.take()
                var tail: ast.Node*? = none
                while not self.at_op("]"):
                    let e = try self.parse_expression()
                    ast.append(&a.body, &tail, e)
                    if not self.eat_op(","):
                        break
                # the literal's extent, so the formatter can keep a commented one as written
                let close = self.cur()
                try self.expect_op("]")
                a.end = close.end
                return a
            if s == "(":
                if self.looks_like_lambda():
                    return try self.parse_lambda()
                # the group, tuple, or unit begins at its bracket
                let open = self.take()
                if self.eat_op(")"):
                    let u = try self.node(ast.Kind.unit_, "")
                    u.start = open.start
                    u.line = open.line
                    return u
                let first = try self.parse_expression()
                if self.at_op(","):
                    let tuple = try self.node(ast.Kind.tuple, "")
                    tuple.start = open.start
                    tuple.line = open.line
                    var tail: ast.Node*? = none
                    ast.append(&tuple.body, &tail, first)
                    while self.eat_op(","):
                        if self.at_op(")"):
                            break
                        let e = try self.parse_expression()
                        ast.append(&tuple.body, &tail, e)
                    try self.expect_op(")")
                    return tuple
                try self.expect_op(")")
                let g = try self.node(ast.Kind.group, "")
                g.start = open.start
                g.line = open.line
                g.left = first
                return g
        if self.at_op("\\"):
            # most often `\"` in a format field, which is code, not the string around it
            return try self.fail("a backslash escapes only inside a string; a format field's expression writes its strings with plain quotes, `{name if name != \"\" else \"none\"}`")
        return try self.fail("expected an expression")

    ## `u8[](pointer, count)`: a type, `[]`, then arguments.
    func looks_like_span_constructor() -> bool:
        var i: usize = 1
        while self.peek_op(i, ".") and self.peek(i + 1).kind == token.Kind.name:
            i += 2
        return self.peek_op(i, "[") and self.peek_op(i + 1, "]") and self.peek_op(i + 2, "(")

    ## `(a, b) => body` or `() => body`: a parameter list, names each with an optional
    ## type, followed by `=>`. `(n < 0) => x` in a match arm is a guard's parenthesised
    ## condition, not a lambda, because `n < 0` is no parameter (§9.6, §8.4).
    func looks_like_lambda() -> bool:
        var i: usize = 1
        var depth: u32 = 1
        var after_colon = false
        while depth > 0:
            let t = self.peek(i)
            if t.kind == token.Kind.eof:
                return false
            if t.kind == token.Kind.operator:
                let s = self.text_of(t)
                if s == "(":
                    # a nested `(` opens a tuple type after `:`; `((n < 0))` is no parameter
                    if depth == 1 and not after_colon:
                        return false
                    depth += 1
                elif s == ")":
                    depth -= 1
                elif depth == 1 and s != "," and s != ":" and s != "[" and s != "]" and s != "*" and s != "*?" and s != "?" and s != "!" and s != "->" and s != ".":
                    return false
                if depth == 1:
                    after_colon = s == ":"
            elif depth == 1 and t.kind != token.Kind.name and not (t.kind == token.Kind.keyword and (self.text_of(t) == "func" or self.text_of(t) == "const")):
                return false
            i += 1
        return self.peek_op(i, "=>")

    func parse_lambda() -> ast.Node*!:
        let n = try self.node(ast.Kind.lambda, "")
        try self.expect_op("(")
        var tail: ast.Node*? = none
        while not self.at_op(")"):
            let p = try self.node(ast.Kind.param, "")
            p.text = try self.expect_name()
            if self.eat_op(":"):
                p.ty = try self.parse_type()
            ast.append(&n.right, &tail, p)
            if not self.eat_op(","):
                break
        try self.expect_op(")")
        try self.expect_op("=>")
        n.body = try self.parse_expression()
        return n

    func parse_formatted() -> ast.Node*!:
        let n = try self.node(ast.Kind.formatted, "")
        _ = self.take()
        var tail: ast.Node*? = none
        while not self.at(token.Kind.format_end):
            if self.at(token.Kind.format_text):
                let part = try self.taken(ast.Kind.format_text)
                ast.append(&n.body, &tail, part)
            elif self.eat_op("{"):
                let field = try self.node(ast.Kind.format_field, "")
                field.left = try self.parse_expression()
                # `{value:spec}`: the specification is the field's text (§5.5)
                if self.at(token.Kind.format_spec):
                    field.text = self.text_of(self.take())
                try self.expect_op("}")
                ast.append(&n.body, &tail, field)
            else:
                _ = try self.fail("expected formatted string text or a field")
        _ = self.take()
        return n

    ## `new T(args)`, `new T[n]`, `new Kind.case(args)`, `new T`, with `in allocator`.
    func parse_new() -> ast.Node*!:
        let n = try self.node(ast.Kind.new_, "")
        try self.expect_kw("new")
        n.ty = try self.parse_type()
        if self.at_op("("):
            # Preserve an explicit empty constructor call separately from zeroed `new T`.
            n.text = "()"
            n.body = try self.parse_arguments()
        elif self.eat_op("."):
            let value = try self.node(ast.Kind.case_value, "")
            value.text = try self.expect_member_name()
            if self.at_op("("):
                value.body = try self.parse_arguments()
            n.body = value
        elif self.eat_op("---"):
            # `new T[count] ---`: the elements stay unwritten (§12.2)
            n.kind = ast.Kind.new_unwritten
        if self.eat_kw("in"):
            n.right = try self.parse_else()  # a `catch` after the allocator handles the allocation
        return n

    # -- types ----------------------------------------------------------------------------
    pub func parse_type() -> ast.Node*!:
        var flags: u32 = 0
        # `@` marks the whole type, suffixes included: `@Node*?` is an atomic nullable pointer
        let atomic = self.eat_op("@")
        while self.at_kw("const") or self.at_kw("volatile"):
            if self.eat_kw("const"):
                flags |= ast.flag_const
            else:
                _ = self.take()
                flags |= ast.flag_volatile
        var t = try self.parse_type_core()
        t.flags |= flags
        var pointee = false
        var suffixed = false  # after a suffix, a bracket can only be another suffix
        while true:
            suffixed = true
            if self.at_op("*") or self.at_op("*?"):
                let nullable = self.at_op("*?")
                _ = self.take()
                pointee = true
                let p = try self.node(ast.Kind.type_, "*")
                p.flags |= ast.flag_star
                p.left = t
                t = p
                if nullable:
                    let o = try self.node(ast.Kind.type_, "?")
                    o.flags |= ast.flag_optional
                    o.left = t
                    t = o
            elif self.at_op("[") and (self.array_suffix_ahead() or suffixed):
                var first_suffix: ast.Node*? = none
                var last_suffix: ast.Node*? = none
                while self.at_op("["):
                    _ = self.take()
                    let s = try self.node(ast.Kind.type_, "[")
                    if self.eat_op("]"):
                        s.flags |= ast.flag_span
                    else:
                        s.flags |= ast.flag_array
                        s.right = try self.parse_expression()
                        try self.expect_op("]")
                    ast.append(&first_suffix, &last_suffix, s)
                # the run applies inside-out as in C: `u8[2][4]` is two arrays of four (§5.4)
                t = try nest_suffixes(first_suffix, t)
            else:
                break
        if (flags & ast.flag_volatile) != 0 and not pointee:
            return try self.fail("`volatile` qualifies a pointee: write `volatile T*` (§15.2)")
        if self.eat_op("?"):
            let o = try self.node(ast.Kind.type_, "?")
            o.flags |= ast.flag_optional
            o.left = t
            t = o
            if self.at_op("["):
                return try self.fail("`?` suffixes the whole type before it: an array or span of optionals is written `(T?)[N]` or `(T?)[]` (§5.4)")
        if atomic:
            t.flags |= ast.flag_atomic
        if self.eat_op("!"):
            let f = try self.node(ast.Kind.type_, "!")
            f.flags |= ast.flag_fallible
            f.left = t
            t = f
        return t

    ## Whether the bracket at the cursor holds something no type can: an arithmetic or
    ## comparison operator, a literal past the first token, a lowercase field after a dot,
    ## or `*` between operands. Such a bracket is an index or an array length whatever its
    ## first name looks like (§5.4, §7.6); one holding only names is decided by what the
    ## names resolve to, in the checker.
    func bracket_holds_expression() -> bool:
        var i: usize = 1
        var depth: u32 = 0
        while true:
            let t = self.peek(i)
            if t.kind == token.Kind.eof or t.kind == token.Kind.newline:
                return false
            let s = self.text_of(t)
            if t.kind == token.Kind.operator:
                if s == "(" or s == "[":
                    depth += 1
                    i += 1
                    continue
                if s == ")" or s == "]":
                    if depth == 0:
                        return false
                    depth -= 1
                    i += 1
                    continue
            if depth > 0:
                i += 1
                continue
            let after = self.peek(i + 1)
            if t.kind == token.Kind.operator:
                if s == "+" or s == "-" or s == "/" or s == "//" or s == "%" or s == "<" or s == ">" or s == "<=" or s == ">=" or s == "==" or s == "!=" or s == "|" or s == "^" or s == ".." or s == "..<" or s == "<<" or s == ">>":
                    return true
                if s == "*" and (after.kind == token.Kind.name or after.kind == token.Kind.integer or (after.kind == token.Kind.operator and self.text_of(after) == "(")):
                    return true  # `a * b`, not `T*`
                if s == "." and after.kind == token.Kind.name and i > 1:
                    let ab = self.text_of(after).bytes
                    if ab.length > 0 and ab[0] >= 'a' and ab[0] <= 'z' and self.text_of(self.peek(i - 1)) != "c":
                        return true  # `s.count`: a field, not `module.Type`
            elif t.kind == token.Kind.integer:
                if i > 1:
                    return true  # `T[3]` is an array type; `n - 3` is not
            elif t.kind == token.Kind.float or t.kind == token.Kind.character or t.kind == token.Kind.text:
                return true
            elif t.kind == token.Kind.keyword and (s == "and" or s == "or" or s == "not"):
                return true
            i += 1

    ## `[` after a type: an array or span suffix unless it holds type arguments.
    func array_suffix_ahead() -> bool:
        let t = self.peek(1)
        if t.kind == token.Kind.operator and self.text_of(t) == "]":
            return true
        if t.kind == token.Kind.operator and self.text_of(t) == "(" and self.tuple_type_at(2):
            return false  # `Box[(i64, str)]`: a tuple type argument, not `T[(n)]`
        if self.bracket_holds_expression():
            return true
        if t.kind == token.Kind.keyword:
            let word = self.text_of(t)
            # Qualifiers and function signatures start type arguments, never
            # array lengths: `Callback[const u8[], unit]` must reach parse_type.
            return word != "const" and word != "volatile" and word != "func"
        if t.kind == token.Kind.integer:
            return true
        if t.kind == token.Kind.operator and self.text_of(t) == "(":
            return true
        if t.kind == token.Kind.name:
            let w = self.text_of(t)
            # `List[ir.Instr]`: a module-qualified type is a type argument, not a length
            return not is_type_word(w) and not self.qualified_type_ahead(1)
        return false

    ## Whether the tokens from `ahead` spell `module.Type`.
    func qualified_type_ahead(ahead: usize) -> bool:
        return self.peek(ahead).kind == token.Kind.name and self.peek_op(ahead + 1, ".") and self.peek(ahead + 2).kind == token.Kind.name and is_type_word(self.text_of(self.peek(ahead + 2)))

    func parse_type_core() -> ast.Node*!:
        if self.eat_kw("func"):
            let t = try self.node(ast.Kind.type_, "func")
            t.flags |= ast.flag_func_type
            try self.expect_op("(")
            var tail: ast.Node*? = none
            while not self.at_op(")"):
                let p = try self.parse_type()
                ast.append(&t.body, &tail, p)
                if not self.eat_op(","):
                    break
            try self.expect_op(")")
            try self.expect_op("->")
            t.left = try self.parse_type()
            return t
        if self.at_name("void"):
            let t = try self.node(ast.Kind.type_, "void")
            _ = self.take()
            t.flags |= ast.flag_void
            return t
        if self.eat_op("("):
            let first = try self.parse_type()
            if self.eat_op(","):
                let tuple = try self.node(ast.Kind.type_, "tuple")
                tuple.flags |= ast.flag_tuple_type
                var tail: ast.Node*? = none
                ast.append(&tuple.body, &tail, first)
                while not self.at_op(")"):
                    let next = try self.parse_type()
                    ast.append(&tuple.body, &tail, next)
                    if not self.eat_op(","):
                        break
                try self.expect_op(")")
                return tuple
            try self.expect_op(")")
            let g = try self.node(ast.Kind.type_, "(")
            g.left = first
            return g
        if not self.at(token.Kind.name):
            _ = try self.fail("expected a type")
        let first = self.take()
        var last = first
        var segments: u32 = 1
        while self.at_op(".") and self.peek(1).kind == token.Kind.name and (is_type_word(self.text_of(self.peek(1))) or self.text_of(first) == "c" or (segments == 1 and not is_type_word(self.text_of(first)) and not self.peek_op(2, "("))):
            _ = self.take()
            last = self.take()
            segments += 1
        let t = try self.node(ast.Kind.type_, self.src.text(first.start, last.end))
        if self.at_op("[") and not self.array_suffix_ahead():
            t.body = (try self.parse_type_args()).body
        return t

func is_assign_op(spelling: str) -> bool:
    let ops: str[18] = ["=", "+=", "-=", "*=", "/=", "//=", "%=", "+%=", "-%=", "*%=", "+|=", "-|=", "*|=", "&=", "|=", "^=", "<<=", ">>="]
    for op in ops:
        if op == spelling:
            return true
    return false

func is_type_word(word: str) -> bool:
    let core: str[20] = ["i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "usize", "isize", "f16", "f32", "f64", "bool", "char", "str", "fmt", "unit", "never", "void"]
    for core_name in core:
        if core_name == word:
            return true
    let b = word.bytes
    return b.length > 0 and b[0] >= 'A' and b[0] <= 'Z'

## The element type wrapped by a run of suffixes, last suffix innermost.
func nest_suffixes(first: ast.Node*?, elem: ast.Node*) -> ast.Node*!:
    let s = first else return elem
    let inner = try nest_suffixes(s.next, elem)
    s.left = inner
    s.next = none
    return s

# mark: Entry point and tests =================================================================

## Parse `text` as a module in the current allocator.
pub func parse_text(text: str, scratch: u8[]) -> ast.Node*!:
    let src = try source.Source.over("test", text.bytes)
    var p = try Parser.over(src, scratch)
    return try p.parse_module()

test "a function with a body":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let m = try parse_text("pub func add(a: i64, b: i64 = 2) -> i64:\n    return a + b\n", scratch)
        assert(ast.count(m.body) == 1)
        let f = m.body else return
        assert(f.kind == ast.Kind.func_)
        assert(f.has(ast.flag_pub))
        assert(ast.count(f.right) == 2)
        let block = f.body else return
        assert(ast.count(block.body) == 1)

test "struct, enum, and union declarations":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let text = "struct P: A:\n    var x: i64\n    func get() -> i64: return self.x\nenum K as u8:\n    a = 1\n    b(v: i64)\nunion U:\n    i: i64\n    f: f64\n"
        let m = try parse_text(text, scratch)
        assert(ast.count(m.body) == 3)
        let s = m.body else return
        assert(s.kind == ast.Kind.struct_)
        assert(ast.count(s.body) == 2)

test "expression precedence and casts":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let m = try parse_text("let v = (u8)x + 2 * 3 == 8 and not y\n", scratch)
        let content = m.body else return
        let e = content.left else return
        assert(e.kind == ast.Kind.binary)
        assert(e.text == "and")
        let l = e.left else return
        assert(l.text == "==")
        let sum = l.left else return
        assert(sum.text == "+")
        let cast = sum.left else return
        assert(cast.kind == ast.Kind.cast)

test "statements and layout":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let text = "func f() -> !:\n    var i: usize = 0\n    outer: while i < 3:\n        if let v = g(i):\n            i += 1\n        elif i == 2:\n            break outer\n        else:\n            continue\n    for (k, x) in items.indexed():\n        defer free(x)\n    match k:\n        .a, .b(v): return\n        1..<3 if k > 0: pass_()\n        _: trap()\n    let r = risky() catch failure:\n        recover 0\n"
        let m = try parse_text(text, scratch)
        let f = m.body else return
        let block = f.body else return
        assert(ast.count(block.body) == 5)

test "a match expression ends with its arms":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let text = "func f(n: i64, p: i64*) -> i64:\n    let w = match n:\n        0 => 1\n        _ => 2\n    if w == 1:\n        return 3\n    let v = match n:\n        0 => 1\n        _ => 2\n    *p = v\n    return w\n"
        let m = try parse_text(text, scratch)
        let f = m.body else return
        let block = f.body else return
        assert(ast.count(block.body) == 5)

test "a nested tuple is a type argument":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let text = "func f() -> Box[((i64, i64), str)]:\n    return Box[((i64, i64), str)](item = ((1, 2), \"s\"))\n"
        let m = try parse_text(text, scratch)
        let f = m.body else return
        let r = f.ty else return
        assert(r.body != none)

test "types":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let m = try parse_text("var a: const u8[]?\nvar b: func(i64, Node*?) -> unit\nvar c: (i64, str)\nvar d: Map[str, u32]\nvar e: @u32\n", scratch)
        assert(ast.count(m.body) == 5)
        let a = m.body else return
        let at = a.ty else return
        assert(at.has(ast.flag_optional))

test "a syntax error names its position":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    var failed = false
    with arena:
        let result = parse_text("func f(:\n", scratch) catch failure:
            assert(failure.message == "test:1:8: expected a name")
            failed = true
            recover try ast.Node.make(ast.Kind.unit_, "", 0, 0)
        _ = result
    assert(failed)

test "uninitialised var":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let m = try parse_text("func f():\n    var a: i64 = ---\n", scratch)
        let f = m.body else return
        let block = f.body else return
        let v = block.body else return
        assert(v.has(ast.flag_uninit))

test "dash operator token":
    var backing: u8[65536]
    var arena = memory.FixedBuffer.over(backing)
    var scratch: u8[256]
    with arena:
        let src = try source.Source.over("t", "= ---".bytes)
        var p = try Parser.over(src, scratch)
        assert(p.count == 3)
        let t1 = p.tokens[1]
        assert(t1.kind == token.Kind.operator)
        assert(t1.end - t1.start == 3)
        assert(p.text_of(t1) == "---")
        assert(p.at_op("="))
        assert(p.eat_op("="))
        assert(p.at_op("---"))
        assert(p.eat_op("---"))
        assert(p.at(token.Kind.eof))

## Whether the attribute list names `word`.
## The struct, enum, or union `module` declares under `name`, which an extension adds to.
## Whether callee `e` may be `memory.size_of`, `align_of`, or `offset_of` (§5.11), whose
## first argument may be a type: by its last name, the checker telling which module it is.
func names_a_measure(e: ast.Node*) -> bool:
    if e.kind != ast.Kind.name and e.kind != ast.Kind.member:
        return false
    return e.text == "size_of" or e.text == "align_of" or e.text == "offset_of"

func extended_type(module: ast.Node*, name: str) -> ast.Node*?:
    var cursor = module.body
    while let d = cursor:
        if d.text == name and (d.kind == ast.Kind.struct_ or d.kind == ast.Kind.enum_ or d.kind == ast.Kind.union_):
            return d
        cursor = d.next
    return none

func names_attribute(attributes: ast.Node*?, word: str) -> bool:
    var cursor = attributes
    while let a = cursor:
        if a.text == word:
            return true
        cursor = a.next
    return false